BillerApi

Docs

REST API for biller discovery, account linking, and bill retrieval.

https://api.billerapi.com

Authentication

Most endpoints require IAM credentials. Include these headers with each request.

X-Client-ID: your_client_id
X-Client-Secret: your_client_secret

Gmail OAuth endpoint (/emails/gmail/oauth-url) does not require auth.

Response & Error Codes

Standard HTTP status codes and error response format for all endpoints.

Response Codes
200  Success
201  Created
202  Accepted
400  Bad Request - Invalid parameters or request body
401  Unauthorized - Missing or invalid credentials
403  Forbidden - Insufficient permissions
404  Not Found - Resource not found
429  Too Many Requests - Rate limit exceeded
500  Internal Server Error
Error Response Format
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Biller Discovery (Gmail)

Connect Gmail to discover billers from a user's email.

POSThttps://api.billerapi.com/emails/gmail/oauth-urlNone

Get Gmail OAuth authorization URL. No auth required.

Request Body
{
  "user_id": "string",
  "client_id": "string",
  "redirect_uri": "string (optional)"
}
Response
{
  "success": true,
  "data": {
    "oauth_url": "https://accounts.google.com/o/oauth2/..."
  }
}
Response Codes
200  Success
cURL Example
curl -X POST https://api.billerapi.com/emails/gmail/oauth-url \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user_123","client_id":"client_abc"}'
POSThttps://api.billerapi.com/emails/gmail/connectIAM

Connect Gmail for a user.

Request Body
{
  "user_id": "string",
  "client_id": "string"
}
Response Codes
200  Success
cURL Example
curl -X POST https://api.billerapi.com/emails/gmail/connect \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret" \
  -d '{"user_id":"user_123","client_id":"client_abc"}'
GEThttps://api.billerapi.com/emails/messagesIAM

List email messages for biller discovery.

Query Parameters
userId, startDate, endDate, limit, cursor
Response Codes
200  Success
cURL Example
curl -X GET "https://api.billerapi.com/emails/messages?userId=user_123&limit=50" \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret"

Biller Account Connection

Use the Connect flow to link biller accounts. For the full flow (select biller, credentials, MFA, account discovery), use @billbutler/connect-sdk. Your server only needs these two endpoints: create a link token before opening the SDK, then exchange the public token after the user completes the flow.

View SDK on npm

Biller Retrieval

List and search billers.

GEThttps://api.billerapi.com/billersIAM

List billers with optional filtering.

Query Parameters
search_term, status, type, consent_scope, page, page_size, sort_by, sort_order
Response Codes
200  Success
GEThttps://api.billerapi.com/billers/:idIAM

Get biller by ID.

Response Codes
200  Success
GEThttps://api.billerapi.com/billers/search/by-emailIAM

Search billers by email domain.

Query Parameters
email
Response Codes
200  Success

Bills

Retrieve bills and manage sync for linked accounts.

GEThttps://api.billerapi.com/bills/getIAM

Get bills for an account link.

Query Parameters
account_link_id, start_date, end_date, limit, cursor
Response Codes
200  Success
cURL Example
curl -X GET "https://api.billerapi.com/bills/get?account_link_id=link_123&limit=50" \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret"
GEThttps://api.billerapi.com/bills/:idIAM

Get bill by ID. Supports Bearer (access token) or IAM credentials.

Response Codes
200  Success
POSThttps://api.billerapi.com/bills/sync/triggerIAM

Trigger bill sync for an account link.

Request Body
{
  "account_link_id": "string",
  "force": "boolean (optional)"
}
Response Codes
202  Accepted
GEThttps://api.billerapi.com/bills/syncIAM

Get sync status for an account link.

Query Parameters
account_link_id, since, limit, include_deleted
Response Codes
200  Success
GEThttps://api.billerapi.com/bills/accountsIAM

Get connected accounts for the client.

Response Codes
200  Success

Ready to integrate?

Sign up for a developer account to get your API keys.

Sign up