API reference

Submits one borrower referral. Requires an executed MSA; provider-paid and split-pay referrals also need a billing method. Send an Idempotency-Key header to make retries safe: a replay returns the original referral with idempotent_replay: true and 200. Keys are per institution and per key mode: the same key sent with a live key and a test key makes two referrals, and a live key can't send a key that starts with test: (409 idempotency_key_mode_conflict). A key that doesn't hold referrals:read gets an acknowledgement instead of the referral: its id, object and status, never its data. Such a key's replay must repeat its own request exactly: a key that came with a different request, or with one sent before requests were fingerprinted, is 422 idempotency_key_reused. Test keys (sa_gap_test_... or sa_test_...) get 403 test_key_referrals_unavailable until the referral sandbox opens; from then on a test key reaches sandbox referrals only, and a live key never sees them.

Your referrals, newest first, a page at a time. Once a borrower withdraws permission to report a referral's progress to you, the referral shows status: reporting_withdrawn and reporting_withdrawn_at, the fields you supplied, and no progress. status matches the status shown: reporting_withdrawn lists those referrals, and any other status leaves them out. Test keys (sa_gap_test_... or sa_test_...) get 403 test_key_referrals_unavailable until the referral sandbox opens; from then on a test key reaches sandbox referrals only, and a live key never sees them.

The full referral, with the provider-facing milestone timeline and the financial panel. Once a borrower withdraws permission to report a referral's progress to you, the referral shows status: reporting_withdrawn and reporting_withdrawn_at, the fields you supplied, and no progress. Its timeline and financial are then null, as are consultation_number and days_in_negotiation. Test keys (sa_gap_test_... or sa_test_...) get 403 test_key_referrals_unavailable until the referral sandbox opens; from then on a test key reaches sandbox referrals only, and a live key never sees them.

loan_payoff_cents and deductible_cents are editable any time. Every other field, and the program terms, until the borrower activates (409 after). { "action": "cancel" }, sent on its own, cancels before activation (409 after). A referral whose borrower withdrew permission to report its progress is 409 reporting_withdrawn, whatever the request asks, and nothing is written. A key that doesn't hold referrals:read gets an acknowledgement instead of the referral: its id, object and status, never its data. Test keys (sa_gap_test_... or sa_test_...) get 403 test_key_referrals_unavailable until the referral sandbox opens; from then on a test key reaches sandbox referrals only, and a live key never sees them.

Up to 500 referrals in one call. Each row is validated and created on its own: valid rows are created even when siblings fail, and results reports every row. A row may carry its own idempotency_key and, for a warm handoff, its disclosure. An institution without an executed MSA gets 403 msa_required for the whole call; a provider-paid or split-pay row without a billing method fails with the row code billing_required. A key that doesn't hold referrals:read gets each row's referral as an acknowledgement (its id, object and status), and its rows replay only their own requests, as a single create's do. Test keys (sa_gap_test_... or sa_test_...) get 403 test_key_referrals_unavailable until the referral sandbox opens; from then on a test key reaches sandbox referrals only, and a live key never sees them.

Test keys only. Moves one of your sandbox referrals one step along its lifecycle, and sends the webhook event a live referral sends at that step (referral.invited, referral.activated, referral.declined or settlement.updated) to your test endpoints, marked livemode: false. Nothing reaches a borrower and nothing is billed. A key that doesn't hold referrals:read gets an acknowledgement instead of the referral: its id, object and status, never its data. A live key gets 403 simulate_requires_test_key, an id that is not one of your sandbox referrals 404, and a step off the lifecycle 409 invalid_transition. A referral whose borrower withdrew permission to report its progress is 409 reporting_withdrawn, whatever the request asks, and nothing is written. Staged: it opens with the referral sandbox, and until then every call answers 404 operation_not_open.

For a warm-handoff referral created without its disclosure: you certify that your staff delivered the disclosure script and that the borrower agreed to be contacted, the same attestation as create's disclosure, and the referral is queued for our outreach. Accepted only while the referral waits for its attestation: after that, or for an invitation referral, it is a 409 invalid_transition. A script version that is not the current script is a 409 script_version_stale. A referral whose borrower withdrew permission to report its progress is 409 reporting_withdrawn, whatever the request asks, and nothing is written. A test key attests its sandbox referrals, which reach no one: no outreach is opened for them. A key that doesn't hold referrals:read gets an acknowledgement instead of the referral: its id, object and status, never its data. Staged: it opens with the referral sandbox, and until then every call answers 404 operation_not_open.

Finds your referrals by one identifier, sent in the body so it never travels in a URL: vin, claim_number or external_ref, as you sent it on the referral. Each match comes with the latest version of its review record, cited as { id, version, hash } with its status and when it was written, and with its close reason: what the review webhooks carry. Read the version itself with GET /api/gap/v1/referrals/{id}/review-record. Newest first, at most 100 (has_more says more matched); no match is an empty list. record is null while a referral's record has no version to show: before its first, and from the borrower's request that we stop reporting the referral's progress until the version that records it. It writes nothing, but during a failover the platform can still answer it as it answers a write (503 platform_standby). Test keys (sa_gap_test_... or sa_test_...) get 403 test_key_referrals_unavailable until the referral sandbox opens; from then on a test key reaches sandbox referrals only, and a live key never sees them. Staged: it opens with review records, once their sweep is on and has finished its first pass; until then every call answers 404 operation_not_open.

One version of the referral's review record: the latest, or the one ?version= names. A version is written each time the record changes and never edited, and its hash is the SHA-256 of bundle's canonical JSON (RFC 8785), so the version you read later still matches the hash a webhook or the lookup cited. bundle holds the record: its status, the verdict once it reached the borrower and whether we can help (never a dollar figure), the review window, outreach, a refusal, a review done elsewhere, the appraisal right, the costs by component and payer, the requirement, the outcome and the copy versions. A redacted version keeps its id, version, hash and status, with bundle: null. Once the borrower asks us to stop reporting the referral's progress, the latest version says only that, and the versions before it stay readable by number; until the version that records it is written, there is no latest to show. 404 not_found for a referral that isn't yours in this key's mode, a version it doesn't have, or a record with no version to show yet. costs.engagement and costs.institution_charges are null unless the key also holds reporting:read. The hash covers the whole record, costs included, so a copy with them null still cites the version but doesn't hash to it. Test keys (sa_gap_test_... or sa_test_...) get 403 test_key_referrals_unavailable until the referral sandbox opens; from then on a test key reaches sandbox referrals only, and a live key never sees them. Staged: it opens with review records, once their sweep is on and has finished its first pass; until then every call answers 404 operation_not_open.

Your referral funnel and activation rate, settled outcomes (uplift, exposure reduction), spend (fees, ROI multiple, net savings), and breakdowns by market and carrier: the numbers the portal's Analytics page shows. Filter on the referral's creation date with from (inclusive) and to (exclusive). Test keys (sa_gap_test_... or sa_test_...) get 403 test_key_referrals_unavailable until the referral sandbox opens; from then on a test key reaches sandbox referrals only, and a live key never sees them.

Idempotent per institution and key mode with the Idempotency-Key header: a replay returns the original with idempotent_replay: true and 200; a key already used in the other mode or for another VIN is a 422 idempotency_key_reused. Partner-billed institutions get an ACTIVE enrollment at once (you are the payer of record); direct-collect institutions get a PENDING one with an activation_url for the member.

Your enrollments in this key's mode, newest first. A key scoped to read may list, and an institution whose membership gate is closed can still read its roster.

One of your enrollments in this key's mode.

{ "cancel": true }, on its own, cancels: at once for a partner-billed enrollment, at period end for a direct-collect one. { "new_vin": … } enrolls the new VIN and closes this enrollment (201): the new vehicle's eligibility window starts again; garaged_state, external_ref and each member field carry over unless sent, and a paying direct-collect member's subscription moves to the new enrollment. Any other body edits external_ref and member only; a body with nothing to apply is a 400. In external_ref, send your own enrollment or file ID. Never a loan, account or policy number (a credit union member number is an account number).

Each row is validated and enrolled on its own; results reports every row. A row's idempotency_key replays it like the single endpoint's header. An Idempotency-Key header (at most 251 characters) keys every row without its own as <header>:<index>, so re-sending the same batch replays it.

Every VIN in the list ends up live; every live VIN of yours not in the list is cancelled (you stopped billing that member), at period end for a paying direct-collect member. Only an explicit { "enrollments": [] } empties the roster; a bare array is refused. Any malformed row refuses the whole sync (400 with rejected), so a parse error can never cancel a live member. Built for a nightly job from a loan-servicing system. In external_ref, send your own enrollment or file ID. Never a loan, account or policy number (a credit union member number is an account number).

The payoff-request trigger: you usually know before the member does. Records the notice on the enrollment so we can reach the member with a running start. 404 not_a_member_vehicle when the VIN is not a live member vehicle of yours; a date_of_loss more than a day ahead is a 400.

Ids, VIN, status, dates and the outcome once settled: never the consultation's internals. Newest first, a page at a time. A redemption names the referral its member consultation made (referral_id); once the borrower withdraws permission to report that referral's progress to you, the redemption shows status: REPORTING_WITHDRAWN and reporting_withdrawn_at, with no outcome and no settled_at, as the referral itself reads (status: reporting_withdrawn).

Your last 36 monthly statements, newest first. A test key gets an empty list: statements bill only live enrollments.

Your institution's events from the last 30 days, oldest first: every event we record for you, whether or not a webhook endpoint takes it, as a thin event (ids, your external_ref, statuses, the milestone reached, outcome codes and timestamps; never a borrower's contact details, a payoff, a VIN or an amount). Each event type needs its own permission: the referral and review events referrals:read, charge.created reporting:read, and the membership plan events plans:read. A key lists only the types it holds the permission for, and a key that holds none of them gets an empty list; a key without referrals:read gets each event's referral as its id only. The membership plan events are listed only while the membership program is open to your institution, and a test key lists the referral and charge events only once the referral sandbox opens, as those operations answer. The review events (review.completed, review.updated and referral.closed) are listed only while review records are open, as the review-status lookup and the review record answer. Once a borrower withdraws permission to report a referral's progress, its events from before the withdrawal stay listed, and from the withdrawal on, only the event that announces it is listed (referral.closed, or review.updated citing the REPORTING_WITHDRAWN version); its charge.created and the membership plan's enrollment and statement events stay, while plan.benefit.redeemed and plan.benefit.completed follow the referral the redemption made. A live key lists live events, and a test key sandbox ones. An event is listed about a minute after it happens. To poll, keep the next_cursor every page returns and send it as starting_after, never an event's id: an event can reach the feed after a newer one's webhook has gone out, so a position taken from a webhook would skip it. Webhooks and the feed carry the same event ids, so drop duplicates by id across both. Which types are listed is decided when you read: the events of a surface closed then are not listed later to a poller that has read past them. To see them, or after a 400 invalid_cursor (a cursor works only for the institution and mode it was issued to), start again without starting_after: the feed lists the last 30 days, and you drop the ids you have. Staged: it opens with the partner security platform, and until then every call answers 404 operation_not_open.

The OpenAPI 3.1 document for this API, generated from the contract the API runs on. No key needed. ?oas=3.0 serves a derived OpenAPI 3.0.3 copy.

The same document as GET /api/gap/v1/openapi, under a path ending in .json for tools that expect one.

Which API key made the call and what it may do: its id and prefix, live or test, its format and how it authenticates, the permissions it holds (a legacy key's scopes as the permissions they reach), when it expires, your institution's id and status, and how many address ranges its IP allowlist holds. Any key reaches it, live or test, whatever it may do, so it is the call to make first when a key is refused elsewhere. A terminated institution's key gets 403 provider_terminated.

A signed credential registered in the portal starts unactivated: until this call succeeds, every other call it signs gets 401 credential_not_activated. Sign this call with the credential itself, {id} being its id (the keyid it signs with), with an empty body: the signature proves you hold the private key of the public key you registered. It answers the credential with activated_at, and a later call answers the same time. A public key is active for one credential at most: if another credential has already activated it, this call gets 409 public_key_in_use, and you register a new key pair instead. Any other caller, a bearer key or another credential, gets 404. Staged: it opens when signed credentials open, and until then every call answers 404 operation_not_open.

Planned. For a test credential while you build your signer: send a signed request here and it answers whether the signature verified, with the signature base built from the request as received, to compare byte for byte with yours, and the code the same request would be refused with elsewhere. Test credentials only. Not served yet.