Break a link
Ends the link named by linkId. Call this when a customer disconnects
Bilt inside your product, or when you close their account. It is
an API call you make, not a webhook Bilt subscribes to. The link moves
to LINK_REVOKED.
linkId names which link you are ending, and it is required. One
of your accounts can hold several links over time — a customer
disconnects and reconnects, and each episode is kept rather than
deleted. Without the id, an unlink delayed in your retry queue would
land on whichever link happens to be current, ending one the customer
has since re-created. You do not have to store it: Bilt returns
linkId on the oauth-link response and on the status read.
Idempotent. Unlinking a link that is already ended is 204, not
an error, so retry on a lost response however late — the retry ends
the link it was issued for and never the new one.
409 INVALID_STATE_TRANSITION means the link was busy, not that
your request was wrong. It is only possible for integrations where
Bilt calls you back on unlink: the member disconnects in the Bilt
app, Bilt claims the link and calls you, and your own POST /unlink
arrives inside that window. Back off a second or two and re-send the
identical request.
Authorizations
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
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.
"6f6b1afd-22e0-4137-a096-b15e41cdc890"
Body
The account whose link you are ending.
1 - 256"acme_customer_sandbox_123"
The id of the link episode being ended, as returned on the
oauth-link response and on the status read. Required. An id
that names nothing you may act on answers 404, exactly as an id
that exists nowhere.
"9f1c2e4a-7b30-4d55-8e21-6c0b9a3f5d78"
Response
Link revoked — or already terminal (idempotent retry). No body.