Link Sessions

Create and exchange link tokens to connect your users to their biller accounts via the Connect SDK. A link token initializes the Connect flow, and after the user completes linking, you exchange the public token for a permanent access token.

Related guides: Link a Biller Account | Connect SDK

The Link Token object

Attributes

Field	Type	Description
link_token*	string	The link token used to initialize the Connect SDK
link_token_id*	string	Unique identifier for the link token
client_id*	string	Your client ID
client_user_id*	string	Your unique identifier for the end user
consents*	string[]	Granted consent scopes: "bills", "payments"
redirect_uri	string	URL to redirect the user after linking completes
biller_id	string	Pre-select a specific biller for the Connect flow
created_at	string	ISO 8601 timestamp of when the token was created
expires_at	string	ISO 8601 timestamp of when the token expires

Example Link Token object

JSON

{
  "link_token": "lt_sandbox_abc123def456",
  "link_token_id": "ltid_789xyz",
  "client_id": "your_client_id",
  "client_user_id": "user_12345",
  "consents": ["bills", "payments"],
  "redirect_uri": "https://yourapp.com/callback",
  "biller_id": null,
  "created_at": "2026-04-06T12:00:00Z",
  "expires_at": "2026-04-06T12:30:00Z"
}

POST/link/token/create

Create a link token to start a Connect session. The token is short-lived and should be passed to the Connect SDK on your frontend immediately after creation.

Request Body

Field	Type	Description
client_id*	string	Your BillerAPI client ID
client_user_id*	string	Your unique identifier for the end user
consents*	string[]	Consent scopes to request: "bills", "payments"
redirect_uri	string	URL to redirect the user after linking completes
biller_id	string	Pre-select a specific biller for the Connect flow

Response · 201 Created

{
  "success": true,
  "link_token": "lt_sandbox_abc123def456",
  "link_token_id": "ltid_789xyz"
}

curl -X POST https://sandbox.api.billerapi.com/link/token/create \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret" \
  -d '{
    "client_id": "your_client_id",
    "client_user_id": "user_12345",
    "consents": ["bills", "payments"],
    "redirect_uri": "https://yourapp.com/callback"
  }'

POST/link/token/exchange

Exchange the public token (received after a user completes the Connect flow) for a permanent access token. The access token is used to retrieve bills on behalf of the user.

Request Body

Field	Type	Description
public_token*	string	The public token from the Connect SDK callback
client_id*	string	Your BillerAPI client ID

Response · 200 OK

{
  "success": true,
  "access_token": "at_sandbox_xyz789",
  "biller_id": "test_electric_company",
  "link_id": "link_abc123"
}

curl -X POST https://sandbox.api.billerapi.com/link/token/exchange \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret" \
  -d '{
    "public_token": "pt_sandbox_abc123",
    "client_id": "your_client_id"
  }'