Request to Link

Manage request-to-link (RTL) flows. An RTL represents a request for a user to link their biller account. Create an RTL, track its status, and proceed to a link session when the user is ready.

Related guide: Link a Biller Account

The Request to Link object

Attributes

Field	Type	Description
id*	string	Unique request-to-link identifier
client_id*	string	The client that created the request
client_user_id*	string	Your internal user identifier
biller_id	string	The biller to link (if specified at creation)
status*	string	Status: PENDING, IN_PROGRESS, COMPLETED, CANCELLED, EXPIRED
link_token_id	string	Associated link token ID once linking begins
session_url	string	URL for the link session UI
metadata	object	Custom metadata attached to the request
created_at	string	ISO 8601 timestamp when the request was created
updated_at	string	ISO 8601 timestamp of last update

Example Request to Link object

JSON

{
  "id": "rtl_abc123",
  "client_id": "client_xyz",
  "client_user_id": "user_456",
  "biller_id": "test_electric_company",
  "status": "PENDING",
  "link_token_id": null,
  "session_url": null,
  "metadata": {
    "source": "onboarding"
  },
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-01T10:00:00Z"
}

GET/link/request-to-link

List request-to-link records with optional filtering and pagination.

Query Parameters

Field	Type	Description
search	string	Search by user ID or biller name
status	string	Filter by status: PENDING, IN_PROGRESS, COMPLETED, CANCELLED, EXPIRED
clientUserId	string	Filter by your internal user ID
billerId	string	Filter by biller ID
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 100)

Response

{
  "items": [RequestToLink],
  "total": 12,
  "page": 1,
  "limit": 20
}

curl "https://sandbox.api.billerapi.com/link/request-to-link?status=PENDING&limit=20" \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret"

GET/link/request-to-link/:id

Retrieve a specific request-to-link by ID.

Path Parameters

Field	Type	Description
id*	string	The request-to-link ID

curl https://sandbox.api.billerapi.com/link/request-to-link/rtl_abc123 \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret"

POST/link/request-to-link/create

Create a new request-to-link. This initiates the linking flow for a user.

Request Body

Field	Type	Description
clientId*	string	Your client ID
clientUserId*	string	Your internal user identifier
billerId	string	The biller to link (can be set later)
metadata	object	Custom metadata to attach to the request

Response — 201 Created

{
  "id": "rtl_abc123",
  "client_id": "client_xyz",
  "client_user_id": "user_456",
  "biller_id": "test_electric_company",
  "status": "PENDING",
  "metadata": {
    "source": "onboarding"
  },
  "created_at": "2026-04-01T10:00:00Z"
}

curl -X POST https://sandbox.api.billerapi.com/link/request-to-link/create \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "client_xyz",
    "clientUserId": "user_456",
    "billerId": "test_electric_company",
    "metadata": {
      "source": "onboarding"
    }
  }'

PATCH/link/request-to-link/:id/status

Update the status of a request-to-link. Use this to transition an RTL through its lifecycle.

Path Parameters

Field	Type	Description
id*	string	The request-to-link ID

Request Body

Field	Type	Description
status*	string	New status: PENDING, IN_PROGRESS, COMPLETED, CANCELLED
billerId	string	Set or update the biller ID
linkTokenId	string	Associate a link token with this request

curl -X PATCH https://sandbox.api.billerapi.com/link/request-to-link/rtl_abc123/status \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "IN_PROGRESS",
    "billerId": "test_electric_company",
    "linkTokenId": "lt_token123"
  }'

POST/link/request-to-link/:id/cancel

Cancel a request-to-link. Only RTLs in PENDING or IN_PROGRESS status can be cancelled.

Path Parameters

Field	Type	Description
id*	string	The request-to-link ID

Request Body

Field	Type	Description
reason	string	Optional reason for cancellation

curl -X POST https://sandbox.api.billerapi.com/link/request-to-link/rtl_abc123/cancel \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "User changed their mind"
  }'

POST/link/request-to-link/:id/proceed

Proceed to a link session. This generates a link token and session URL that you can use to redirect the user to the BillerAPI link UI.

Path Parameters

Field	Type	Description
id*	string	The request-to-link ID

Response

{
  "link_token": "lt_token123",
  "session_url": "https://link.billerapi.com/session/lt_token123",
  "expires_at": "2026-04-01T11:00:00Z"
}

curl -X POST https://sandbox.api.billerapi.com/link/request-to-link/rtl_abc123/proceed \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret"