# BillerAPI Documentation > BillerAPI provides APIs for biller discovery, account linking, normalized bills, imports, payments, insights, customer messaging, and webhook delivery for fintech developers. ## Instructions for AI agents ### Environments and keys - Use the sandbox environment (https://sandbox.api.billerapi.com) for all testing. - Server-side API calls use Authorization: Bearer . - Sandbox API keys start with bak_test_; production API keys start with bak_live_. - Only ever use a bak_test_ key when you are acting autonomously. Never create, request, or use a bak_live_ key on a human operator's behalf. - Never put a BillerAPI API key (test or live) in browser code, mobile code, or any client-side bundle. Keys belong in server-side environment variables only. - Never print, echo, log, or commit an API key, client secret, or biller credential — not in a transcript, not in a code comment, not in a commit message. Reference them by env var name. - Never store a secret anywhere but the operator's own secret store or a gitignored .env file. ### API conventions - New BillerAPI request and response fields use snake_case. Treat the generated OpenAPI reference as authoritative: a small number of legacy operations retain documented camelCase fields such as `clientId`, `startDate`, and `endDate`. - Pagination is cursor-based. Most list operations accept `cursor` and return `has_more` plus `next_cursor`; legacy metering operations use the pagination names documented in their generated reference (including `next_token`). Never assume page numbers or offsets. - All timestamps are ISO 8601 UTC. - Errors return a coded envelope: `error_code`, `error_message`, `hint`, `docs_url`, `request_id`. Branch on `error_code`, never on the message text. - List bills server-side with an API key and account_link_id. Link exchange also returns an access token accepted by explicitly documented link-scoped detail and statement operations. ### CLI - The CLI is published to npm as `billerapi-cli`. Check `npm view billerapi-cli version` before use. For the release-attested demo below, the registry version must equal `1.1.0`; if it differs, stop and refresh this index rather than substituting a mutable latest version. - The account-free demo command is withheld until the exact npm publication receipt is available. - `billerapi --help` enumerates every command; discover commands from `--help`, not from assumptions. ### Agent signup release status - Agent setup and sandbox-creation instructions are withheld until an exact npm publication receipt marks billerapi-cli@1.1.0 available and the hosted MCP endpoint has live deployment and canary proof. Do not infer commands from source or unreleased documentation. ### Machine-readable resources - [llms.txt](/llms.txt): This index (also served at /docs/llms.txt). - Markdown docs: every link below that ends in `.md` is the raw-markdown variant of that page — append `.md` to the page URL to get it, e.g. /docs/guides/getting-started.md. Guide and concept markdown carries the page's full text, including code samples the rendered page hides behind language tabs; the API reference, error catalog, and changelog markdown are generated from the OpenAPI document and the catalogs the pages themselves render from. Pages not linked below as `.md` have no markdown variant; requesting one returns 404 rather than a stale file. - [Markdown index](/docs/markdown-index.json): JSON list of every page with a markdown variant (slug, title, description, page_path, markdown_path). Use it to enumerate the docs programmatically. - [OpenAPI JSON](/docs/openapi.json): The served OpenAPI 3.0 spec for the client API. - [Skills catalog](/.well-known/skills/index.json): Agent Skills catalog for this site. - MCP server (COMING SOON — not yet enabled): https://mcp.billerapi.com/mcp (Streamable HTTP). When live: docs tools `search_docs` and `get_doc`, plus `create_claimable_sandbox`, are public; sandbox data tools `list_billers`, `get_biller`, `create_link_token`, `get_bills`, `get_bill` require your SANDBOX key as `Authorization: Bearer ` on the HTTP request — only bak_test_ keys, never bak_live_. Do not call this endpoint until this index marks it live. ## Start Here - [Overview](/docs): Launch-focused docs home and integration path. - [Evaluate BillerAPI](/docs/guides/evaluator-path.md): The one evaluator path, with distinct account-free, owned-account, and consented-agent branches, each carrying one primary action and one fallback. - [Agents and AI](/docs/agents): Stable map for agent onboarding, the copy prompt, and machine-readable entry points. - [Getting Started](/docs/guides/getting-started.md): First integration walkthrough, from sandbox key to bill retrieval. - [Choose an Integration](/docs/guides/integration-paths.md): Map product outcomes to the right API and UI surface. - [Authentication](/docs/guides/authentication.md): Bearer API keys and linked-account access tokens. - [Environments](/docs/concepts/environments.md): Sandbox vs production. - [Magic Account Numbers](/docs/sandbox/magic-numbers): Sandbox test data and deterministic scenarios. ## Core Workflows - [Biller Discovery](/docs/guides/biller-discovery.md): Search supported billers. - [Link a Biller Account](/docs/guides/link-account.md): Create a link token, launch the hosted flow, and exchange the public token. - [Retrieve Bills](/docs/guides/retrieve-bills.md): Fetch bills and statement metadata from connected accounts. - [Import a Bill from an Unlinked Account](/docs/guides/bill-imports.md): Add one bill without a connection, then connect the account when supported for future sync. - [ISO Bill Data Migration](/docs/guides/iso-bill-data-migration.md): Adopt exact ISO 4217 money and calendar-only due dates. - [Set Up Webhooks](/docs/guides/webhooks.md): Register endpoints and verify signed deliveries. - [Webhook Confirmations](/docs/guides/webhook-confirmations.md): Reconcile Elements callbacks with durable signed webhook outcomes. - [Schedule Bill Payments](/docs/guides/accept-payments.md): Create pay tokens and model the hosted scheduling flow. Payment execution is unavailable and answers 501 PAYMENT_EXECUTION_NOT_AVAILABLE. - [Display Biller Messages](/docs/guides/display-biller-messages.md): Required persistence, reconciliation, display, read, report, and consent behavior for connected accounts. - [Feedback](/docs/guides/feedback.md): Submit and track feedback on BillerAPI resources. ## SDKs - [Node SDK](/docs/guides/server-sdk.md): Typed server SDK with retries, pagination, idempotency, and webhook verification. - [CLI](/docs/guides/cli.md): Inspect resources, run the account-free demo when published, and operate a local signed-webhook loop. - [Elements SDK](/docs/guides/elements-sdk.md): Browser integration for hosted biller linking and Elements flows. - [Credential-less Discovery](/docs/guides/credential-less-discovery.md): Preview discovery flow. - [React Native WebView](/docs/guides/react-native-webview.md): Embed the hosted flow in a React Native WebView. - [Link Demo Playground](/docs/guides/connect-demo.md): Public sandbox playground. - [Go Live](/docs/guides/go-live.md): Production rollout checklist. ## Concepts - [Connection Flow Fundamentals](/docs/concepts/connection-flow.md): End-to-end link lifecycle, the hosted flow's step order, and consent scopes. - [API Versioning](/docs/concepts/versioning.md): The /v1 client API contract. - [Changelog](/docs/changelog.md): Public changes and active deprecations (canonical; also served at /docs/concepts/changelog). - [Error Handling](/docs/concepts/errors.md): Error envelope, request IDs, and coded errors. - [Rate Limits](/docs/concepts/rate-limits.md): Rate limit policy and headers. - [Pagination](/docs/concepts/pagination.md): Cursor-based pagination. - [Idempotency](/docs/concepts/idempotency.md): Idempotency keys for safe retries. - [Webhook Delivery](/docs/concepts/webhook-delivery.md): Retry policy, signature verification, and at-least-once semantics. - [Inspecting Requests](/docs/concepts/inspecting-requests.md): Request IDs, logs, and activity. - [OpenAPI Spec](/docs/concepts/openapi.md): Machine-readable OpenAPI 3.0 document. - [Feedback Errors](/docs/concepts/errors/feedback-errors.md): Feedback-specific validation and error codes. - [Error Code Reference](/docs/errors.md): Every stable error_code with its HTTP status, cause, and fix. - [OpenAPI JSON](/docs/openapi.json): The served OpenAPI 3.0 spec for the client API. ## API Reference - [API Reference](/docs/api.md): Resource index. - [Billers](/docs/api/billers.md): Search and retrieve billers. - [Link Sessions](/docs/api/link-sessions.md): Create link tokens and exchange public tokens. - [Pay Sessions](/docs/api/pay-sessions.md): Create and validate pay tokens. - [Pay](/docs/api/pay): Store payment methods and initiate payments where enabled. - [Request to Link](/docs/api/request-to-link.md): Biller-initiated link requests. - [Bills](/docs/api/bills.md): Retrieve bills. - [Bill Imports](/docs/api/bill-imports.md): Upload, review, and commit bill documents. - [Insights](/docs/api/insights.md): Evidence-backed account insights and lifecycle actions. - [Biller Messages](/docs/api/customer-messaging.md): Canonical message retrieval, read state, consent, reporting, and scoped suppression. - [Bill Sync](/docs/api/bill-sync): Trigger and monitor bill sync. (No markdown variant: the endpoints are not serviceable yet.) - [Accounts](/docs/api/accounts): Connected biller accounts. (No markdown variant: the endpoint returns an empty stub today.) - [Biller Discovery](/docs/api/biller-discovery.md): Biller discovery endpoints. - [Webhooks](/docs/api/webhooks.md): Webhook endpoints and events. - [Webhook Payloads](/docs/api/webhooks/payloads): Per-event payload schemas generated from the event catalog. - [Connect Events](/docs/api/connect-events): Hosted flow event taxonomy. - [Feedback](/docs/api/feedback): Submit resource feedback.