BillerAPI — The billing automation API for fintech developers

The Request to Link object

A request-to-link (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.

Attributes

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_idstring	The biller to link (if specified at creation)
status*string	Status: PENDING, IN_PROGRESS, COMPLETED, CANCELLED, EXPIRED
link_token_idstring	Associated link token ID once linking begins
session_urlstring	URL for the link session UI
metadataobject	Custom metadata attached to the request
created_atstring	ISO 8601 timestamp when the request was created
updated_atstring	ISO 8601 timestamp of last update

The Request to Link object

{
  "id": "rtl_abc123",
  "client_id": "client_xyz",
  "client_user_id": "user_456",
  "biller_id": "sb_utility",
  "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/v1/request-to-links

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

Query parameters

searchstring	Search by user ID or biller name
statusstring	Filter by status: PENDING, IN_PROGRESS, COMPLETED, CANCELLED, EXPIRED
client_user_idstring	Filter by your internal user ID
biller_idstring	Filter by biller ID
limitinteger	Page size (default: 50, max: 200)
cursorstring	Opaque cursor from a prior response’s next_cursor. Omit for the first page.

Not available in sandbox yet. These endpoints are live in production only — the sandbox host answers them with 404 NOT_FOUND. Sandbox support is planned; until then, exercise this API with a production key against the production host.

curl "https://api.billerapi.com/v1/request-to-links?status=PENDING&limit=20" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

Response

{
  "items": [RequestToLink],
  "total": 12,
  "limit": 20,
  "next_cursor": "eyJvIjoyMH0=",
  "has_more": true
}

GET/v1/request-to-links/:id

Retrieve a specific request-to-link by ID.

Path parameters

id*string

The request-to-link ID

Not available in sandbox yet. These endpoints are live in production only — the sandbox host answers them with 404 NOT_FOUND. Sandbox support is planned; until then, exercise this API with a production key against the production host.

curl https://api.billerapi.com/v1/request-to-links/rtl_abc123 \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

POST/v1/request-to-links

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

Request body

client_user_id*string	Your internal user identifier
biller_idstring	The biller to link (can be set later)
client_idstring	Optional. Resolved from your API key; send it only to assert the client you expect.
metadataobject	Custom metadata to attach to the request

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

curl -X POST https://sandbox.api.billerapi.com/v1/request-to-links \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_user_id": "user_456",
    "biller_id": "sb_utility",
    "metadata": {
      "source": "onboarding"
    }
  }'

Response201 Created

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

PATCH/v1/request-to-links/:id/status

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

Path parameters

id*string

The request-to-link ID

Request body

status*string	New status: PENDING, IN_PROGRESS, COMPLETED, CANCELLED
biller_idstring	Set or update the biller ID
link_token_idstring	Associate a link token with this request

Not available in sandbox yet. These endpoints are live in production only — the sandbox host answers them with 404 NOT_FOUND. Sandbox support is planned; until then, exercise this API with a production key against the production host.

curl -X PATCH https://api.billerapi.com/v1/request-to-links/rtl_abc123/status \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "IN_PROGRESS",
    "biller_id": "sb_utility",
    "link_token_id": "lt_token123"
  }'

POST/v1/request-to-links/:id/cancel

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

Path parameters

id*string

The request-to-link ID

Request body

reasonstring

Optional reason for cancellation

Not available in sandbox yet. These endpoints are live in production only — the sandbox host answers them with 404 NOT_FOUND. Sandbox support is planned; until then, exercise this API with a production key against the production host.

curl -X POST https://api.billerapi.com/v1/request-to-links/rtl_abc123/cancel \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "User changed their mind"
  }'

POST/v1/request-to-links/: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

id*string

The request-to-link ID

Not available in sandbox yet. These endpoints are live in production only — the sandbox host answers them with 404 NOT_FOUND. Sandbox support is planned; until then, exercise this API with a production key against the production host.

curl -X POST https://api.billerapi.com/v1/request-to-links/rtl_abc123/proceed \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

Response

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