Biller Messages
Related guides: Display biller messages · Webhooks · Error handling
Canonical source and delivery semantics
BillerAPI is the canonical message source. Treat customer.message.created as a doorbell: verify it, deduplicate by event id, fetch the message, and upsert your projection. Reconcile with the list endpoint after missed or delayed delivery.
marketing requires explicit consent. Accepted account_update messages must not be silently dropped. Report suppression is scoped to the message's biller and category.
/v1/biller_messagesList canonical messages for a client user. Filter by account link or unread state and use the opaque cursor for reconciliation.
Query parameters
| client_user_id*string | Your stable user id |
| account_link_idstring | Optional connected-account scope |
| unread_onlyboolean | Return only messages without read_at |
| cursorstring | Opaque next cursor |
curl "https://sandbox.api.billerapi.com/v1/biller_messages?client_user_id=user_123&account_link_id=link_123" \
-H "Authorization: Bearer $BILLERAPI_API_KEY"/v1/biller_messages/{message_id}Retrieve one tenant- and user-scoped canonical message after a webhook notification.
Query parameters
| client_user_id*string | Your stable user id |
/v1/biller_messages/{message_id}/readPersist canonical read state. Repeated calls are idempotent.
Query parameters
| client_user_id*string | Your stable user id |
/v1/biller_messages/{message_id}/reportReport a message. BillerAPI verifies the client user and derives biller and category from the owned canonical row before applying scoped suppression.
Query parameters
| client_user_id*string | Your stable user id |
curl -X POST "https://sandbox.api.billerapi.com/v1/biller_messages/msg_123/report?client_user_id=user_123" \
-H "Authorization: Bearer $BILLERAPI_API_KEY" -H "Content-Type: application/json" \
-d '{"reason":"spam"}'/v1/clients/me/suppressionsList scoped complaint suppressions for compliance review and CRM reconciliation.
/v1/clients/me/suppressions/{user_aid}Remove exactly one listed suppression. Send its biller_id and category unchanged; legacy user-wide rows are returned as * / *. Removing a row does not grant marketing consent.
Query parameters
| biller_id*string | Biller scope from the listed suppression row, or * for a legacy row |
| category*account_update | marketing | * | Message category from the listed row; * is valid only with biller_id=* |
/v1/sandbox/biller_messages/emitSandbox only. Emit a deterministic biller message and seed the recovery feed. After you report a fixture, later fixtures with the same user, biller, and category return delivery_status: suppressed and do not enqueue a webhook.
Request body
| client_user_id*string | Sandbox user |
| account_link_id*string | Connected sandbox account link |
| fixture_idstring | Optional deterministic variant for testing subsequent messages |
| categoryaccount_update | marketing | Optional category; defaults to account_update |
/biller-portal/messagesBiller producer surface. Requires an authenticated biller-portal session; BillerAPI derives recipient and biller identity from the active account link.
/v1/customers/{user_aid}/messagesDeprecated and disabled for fintech API keys. A fintech credential never authorizes the caller to speak as a biller; authenticated biller producers use the biller portal surface.
/v1/customers/{user_aid}/complaintsCompatibility complaint route. New integrations should report the owned canonical resource through POST /v1/biller_messages/{message_id}/report.
/v1/customers/{user_aid}/consentsInspect the customer's per-category consent.
/v1/customers/{user_aid}/consentsGrant or revoke marketing or account_update consent and record its source.