Account Linking SDK

Settle a CIBA link

Delivers your customer’s verdict for a link that started in the Bilt app. Bilt matches notificationToken against the pending request minted for your integration — it is the anti-forgery proof, so a partner credential cannot settle another partner’s link — and applies your params through your integration’s handler on Bilt’s side.

Read the two response fields as a pair: linkStatus is what is true now; attempt is what this delivery did.

`attempt`	Meaning
`OK`	This delivery was an approval Bilt accepted — ordinarily `linkStatus: LINKED`. If Bilt’s expiry sweep had already failed the pending link when your approval arrived, `linkStatus` is `LINK_FAILED`: too late, the member re-initiates
`PARTNER_REJECTED`	This delivery settled the link as `LINK_FAILED` because your customer declined. The standard decline code; if your onboarding agreed a different one, that code arrives here instead
(any other code from the guide’s §9.2)	This delivery settled the link as `LINK_FAILED` with that code — most often `ALREADY_LINKED` / `IDENTITY_ALREADY_LINKED` (a conflicting link), or `PARTNER_UNAVAILABLE` (Bilt could not interpret your delivery). Once the token is claimed, even the codes listed as `500`s arrive this way, in-band on a `200`
`ALREADY_CLAIMED`	This delivery settled nothing: the token was already claimed — usually your own earlier delivery whose `200` was lost. `linkStatus` carries the settled state; stand down
`IGNORED`	This delivery settled nothing: recognized as stale or duplicate and dropped

Redelivery is a 200, never an error, so a retry loop can stand down on any 200. Uniqueness conflicts arrive in-band as attempt, never as a 409 — a spent token behind an error would strand the member. The only 409 here is a rare CONCURRENT_UPDATE raised while settling, after the token was claimed — not retryable; the member re-initiates. Full semantics: the guide’s §7.4.

curl --request POST \
  --url https://partnerapi.biltrewards.com/v1/account-links/ciba-callback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "notificationToken": "nt_sandbox_4f1c9be2"
}
'

{
  "linkStatus": "LINKED",
  "attempt": "OK"
}

Authorizations

Authorization

string

header

required

Preferred. A partner access token minted by your partner client with the client-credentials grant — the client you authenticate as, with no member involved. Send it as Authorization: Bearer <access_token> and on no other header. It is a different client from the IdP one that mints member id_tokens, and it is not the member access_token the code exchange returns — see the guide's §5 Authentication.

Headers

x-request-id

string

Optional but strongly recommended: a unique id per request (a UUID is fine). Echoed back as error.requestId so your logs and Bilt's line up. Quote it in every support ticket.

Example:

"6f6b1afd-22e0-4137-a096-b15e41cdc890"

Body

application/json

notificationToken

string

required

The single-use token Bilt sent in the backchannel request. The anti-forgery proof: Bilt matches it against the pending request minted for your integration.

Required string length: 1 - 512

Example:

"nt_sandbox_4f1c9be2"

params

object | null

Your approve/deny payload. Its exact shape is agreed during onboarding — it is interpreted by your integration's handler on Bilt's side and is not part of this envelope. Up to 32 entries, string values, keys up to 128 characters, values up to 2048.

Show child attributes

Example:

{ "result": "approved" }

Response

Delivery resolved — settled, duplicate, or ignored. Read attempt together with linkStatus.

linkStatus

enum<string>

required

The link state after this delivery — what is true now, not what this delivery did. The CIBA settle endpoint reports a wider set than the other endpoints: LINKING_IN_PROGRESS (the winning delivery is still settling) and LINK_FAILED (declined, or a conflict — see attempt) are possible here.

Available options:

LINKING_IN_PROGRESS,

LINKED,

LINK_FAILED,

UNLINKED,

LINK_REVOKED

Example:

"LINKED"

attempt

string

required

What this delivery did: OK (an accepted approval — LINKED, or LINK_FAILED when the approval came after the pending link expired), ALREADY_CLAIMED (the token was already claimed — stand down), IGNORED (stale or duplicate, dropped), or the code the link settled LINK_FAILED with — PARTNER_REJECTED for a decline, ALREADY_LINKED / IDENTITY_ALREADY_LINKED for a conflict, PARTNER_UNAVAILABLE when Bilt could not interpret the delivery, and, once the token is claimed, any other code from the guide's §9.2 including the ones listed there as 500s.

Example:

"OK"

⌘I

curl --request POST \
  --url https://partnerapi.biltrewards.com/v1/account-links/ciba-callback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "notificationToken": "nt_sandbox_4f1c9be2"
}
'

{
  "linkStatus": "LINKED",
  "attempt": "OK"
}