Link Sessions

Create and exchange link tokens to connect your users to their biller accounts via the Elements. 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 · Elements SDK

The Link Token object

A Link Token initializes a Connect session. It is short-lived, scoped to a single end user and set of consents, and passed to Elements on your frontend to start the link flow.

Attributes

link_token*string	The link token used to initialize Elements
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_uristring	URL to redirect the user after linking completes
biller_idstring	Pre-select a specific biller for the Connect flow
created_atstring	ISO 8601 timestamp of when the token was created
expires_atstring	ISO 8601 timestamp of when the token expires

The Link Token object

{
  "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/v1/link-tokens

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

Request body

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_uristring	URL to redirect the user after linking completes
biller_idstring	Pre-select a specific biller for the Connect flow

Sample uses your_client_id · sign in to auto-fill your sandbox key

curl -X POST https://sandbox.api.billerapi.com/v1/link-tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -d '{
    "client_id": "your_client_id",
    "client_user_id": "user_12345",
    "consents": ["bills", "payments"],
    "redirect_uri": "https://yourapp.com/callback"
  }'

Response201 Created

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

POST/v1/link-tokens/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

public_token*string	The public token from the Elements callback
client_id*string	Your BillerAPI client ID

Sample uses your_client_id · sign in to auto-fill your sandbox key

curl -X POST https://sandbox.api.billerapi.com/v1/link-tokens/exchange \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -d '{
    "public_token": "pt_sandbox_abc123",
    "client_id": "your_client_id"
  }'

Response200 OK

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

Was this page helpful?