Read link status
Returns the current link for one of your accounts, including links
that are no longer active (UNLINKED, LINK_REVOKED).
Treat 404 as “not linked.” It is the normal answer for an account
that has never been connected. A link becomes addressable by
partnerUserId only once your oauth-link call completes it, so a
404 never means “start over” on its own — if you have an
oauth-link call in flight, wait for its response.
Bilt does not push link-state changes to partners; poll this endpoint or check it at the point of use if you need to learn that a member unlinked from the Bilt side.
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"
Path Parameters
Your opaque, stable identifier for the account — the value you sent
on oauth-link. Never an email address or phone number.
1 - 256"acme_customer_sandbox_123"
Response
The link keyed to this account, in whatever state it is in.
Partner-facing view of a link. Returned by oauth-link (without
partnerDetails) and by the status read.
The id of this link episode, and the value POST /unlink
requires. One account legitimately owns several historical links,
so ending one means naming which. Published on both the create
response and the status read, so you can always recover it rather
than having to store it.
"9f1c2e4a-7b30-4d55-8e21-6c0b9a3f5d78"
Your opaque user id, echoed back.
"acme_customer_sandbox_123"
The states you can observe on the oauth-link response and the
status read. LINKED is the only usable state. UNLINKED and
LINK_REVOKED are terminal for that link; the next successful
oauth-link creates a fresh one. UNLINKING_IN_PROGRESS is only
reachable for integrations where Bilt calls you on unlink — unusable
but not terminal; re-read later. Do not code against values outside
this list.
LINKED, UNLINKED, LINK_REVOKED, UNLINKING_IN_PROGRESS "LINKED"
When the link became LINKED, ISO-8601 UTC.
"2026-07-31T13:45:00Z"
Non-sensitive metadata Bilt holds about the link. Present on the
status read only; empty ({}) for this integration model —
reserved for future use.