Billers

Search and retrieve billers in the BillerAPI network. Use these endpoints to discover available billers, search by email domain, or retrieve details for a specific biller.

Related guide: Link a Biller Account

The Biller object

A Biller is a company in the BillerAPI network that a user can link to retrieve statements — a utility, lender, telecom, or government agency. Discover billers, then use the biller ID to start a link session.

Attributes

id*string	Unique biller identifier
name*string	Display name of the biller
type*string	Biller category: UTILITY, FINANCIAL, GOVERNMENT, TELECOM, INSURANCE
status*string	ACTIVE, INACTIVE, or MAINTENANCE
credentials_required*boolean	Whether the biller requires user credentials to link
mfa_required*boolean	Whether multi-factor authentication is needed
descriptionstring	Human-readable description of the biller
logo_urlstring	URL to the biller logo image
website_urlstring	Biller website URL
capability_readinessobject	Readiness and evidence keyed by LOGIN, ACCOUNT_DISCOVERY, RETRIEVE_BILL, RETRIEVE_OBSERVED_PAYMENT, and PAY_BILL
ready_for_connectboolean	Whether login and account discovery are currently ready
ready_for_billsboolean	Whether connect and bill retrieval are currently ready
ready_for_payboolean	Whether connect, bill retrieval, payment integration, and the platform payment-execution gate are currently ready
blocking_reasonstring \| null	Primary machine-readable reason the next journey is blocked
next_actionstring \| null	Machine-readable action that can advance readiness

The Biller object

{
  "id": "sb_utility",
  "name": "Sandbox Utility",
  "type": "UTILITY",
  "status": "ACTIVE",
  "credentials_required": true,
  "mfa_required": false,
  "description": "Simulated electric utility biller",
  "capability_readiness": {
    "LOGIN": {
      "capability": "LOGIN",
      "state": "healthy",
      "ready": true,
      "blocking_reason": null,
      "next_action": null,
      "artifact_version": "7",
      "verified_artifact_version": "7",
      "verified_at": "2026-07-11T12:00:00.000Z"
    }
  },
  "ready_for_connect": true,
  "ready_for_bills": true,
  "ready_for_pay": false,
  "blocking_reason": "pay_not_approved",
  "next_action": "approve_pay_capability"
}

The capability readiness object

Each entry explains whether one capability can currently serve traffic and the evidence behind that decision. Use the top-level journey booleans for gating; use blocking_reason and next_action to explain or remediate a blocked journey. ready_for_pay is false while the platform payment-execution compliance gate is disabled, even when the biller integration itself is proven.

Attributes

capability*string	LOGIN, ACCOUNT_DISCOVERY, RETRIEVE_BILL, RETRIEVE_OBSERVED_PAYMENT, or PAY_BILL
state*string	missing, pending, awaiting_credentials, awaiting_mfa, unproven, human_review, healthy, degraded, failed, stale, or unknown
ready*boolean	Whether current evidence permits this capability to serve traffic
evidencestring	exact_artifact_replay, stale_artifact_replay, verification_task, recording_task, configuration, or none
blocking_reasonstring \| null	Machine-readable reason this capability is not ready
next_actionstring \| null	Machine-readable action that can advance this capability
artifact_versionstring \| null	Current automation artifact version used for readiness
digeststring \| null	Digest of the automation artifact used as evidence
verified_artifact_versionstring \| null	Artifact version most recently verified
verification_task_idstring \| null	Task that produced the verification evidence
recording_task_updated_atstring \| null	ISO 8601 timestamp of the current recording task state
verification_task_updated_atstring \| null	ISO 8601 timestamp of the current verification task state
verified_atstring \| null	ISO 8601 timestamp of the latest verification
state_sincestring \| null	ISO 8601 timestamp when the current state began
last_success_atstring \| null	ISO 8601 timestamp of the latest successful run
last_failure_atstring \| null	ISO 8601 timestamp of the latest failed run
updated_atstring \| null	ISO 8601 timestamp when readiness was last updated

Capability readiness

{
  "capability": "RETRIEVE_BILL",
  "state": "stale",
  "ready": false,
  "blocking_reason": "artifact_proof_stale",
  "next_action": "verify_current_artifact",
  "artifact_version": "8",
  "verified_artifact_version": "7",
  "verified_at": "2026-07-10T18:42:00.000Z"
}

GET/v1/billers

List billers with optional filtering and pagination.

Query parameters

search_termstring	Filter billers by name
statusstring	Filter by status: ACTIVE, INACTIVE
typestring	Filter by type: UTILITY, FINANCIAL, etc.
limitinteger	Results per page (default: 100, max: 500)
cursorstring	Opaque pagination cursor from a prior response’s next_cursor. Omit for the first page.

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

curl https://sandbox.api.billerapi.com/v1/billers \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

Response

{
  "billers": [Biller],
  "total_count": 5,
  "has_more": false,
  "next_cursor": "",
  "success": true,
  "message": "Billers retrieved successfully"
}

GET/v1/billers/{id}

Retrieve a specific biller by ID.

Path parameters

id*string

The biller ID

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

curl https://sandbox.api.billerapi.com/v1/billers/sb_utility \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

GET/v1/billers/search/by-email

Search for billers associated with an email address. Useful for discovering which billers a user might have based on their email domain.

Query parameters

email*string

Email address to search for biller matches

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

curl "https://sandbox.api.billerapi.com/v1/billers/search/by-email?email=user@example.com" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

Was this page helpful?