> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bilt.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Account linking overview

> Connect a Bilt member to an account in your product, from the Bilt app or from your app

## What it is

An account link connects one Bilt member to one account in your product. Either side can read or end it. A member has at most one active link with you, and each of your accounts links to at most one member.

## How it works

Most links start in the Bilt app, which is the primary flow. The member picks your product in the Bilt app, and Bilt calls the [endpoints you host](/api-reference/endpoints-you-host/look-up-a-contact.md) under `/bilt`. A member can also start from your app: they sign in to Bilt, and your backend calls the [account links API](/api-reference/account-links/create-a-link.md).

```mermaid theme={null}
flowchart LR
    A[Member picks you in the Bilt app] --> B[Bilt calls /bilt/lookup-contact]
    B --> C[Bilt calls /bilt/link-account]
    C --> D[(Link: LINKED)]
    D --> E[Either side ends it]
```

## Key concepts

### Link states

Every link has a `linkStatus`. Only `LINKED` is usable.

* `LINKED`: the member is connected.
* `UNLINKED`: the member or Bilt support ended the link.
* `LINK_REVOKED`: you ended the link.
* `UNLINKING_IN_PROGRESS`: Bilt is calling you to end the link. Treat it as unusable but not final, and read the link again.

After `UNLINKED` or `LINK_REVOKED`, a new link gets a new `linkId`. Bilt keeps ended links as history.

### Reading state

Bilt does not push status changes, so read the link with [Get a link](/api-reference/account-links/get-a-link.md). Internal states show as a `404`.

### Who hosts what

You host the endpoints Bilt calls, at base URLs agreed during onboarding. Bilt hosts the account links API under `/v1/account-links`. Build the flow your agreement names.

## Next steps

> **[Link from the Bilt app](/partners/account-linking/link-from-the-bilt-app.md)**
>
> The primary flow. The member starts in the Bilt app, and Bilt calls endpoints you host.

> **[Link from your app](/partners/account-linking/link-from-your-app.md)**
>
> The member signs in to Bilt, and your backend creates the link.

> **[Unlink an account](/partners/account-linking/unlink-an-account.md)**
>
> End a link from either side.

> **[Environments and credentials](/partners/environments-and-credentials.md)**
>
> Get your clients and keys first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.