Biller Discovery

Connect a user's Gmail account to automatically discover which billers they have accounts with. BillerAPI scans incoming billing emails, identifies billers, and extracts bill data.

The Email Message object

An Email Message is a billing email BillerAPI scanned from a connected Gmail inbox, with the biller it matched and any bill amount / due date it extracted.

Attributes

id*string	Unique message identifier
user_id*string	The user who owns this message
from*string	Sender email address
subjectstring	Email subject line
biller_idstring	Matched biller ID (if identified)
biller_namestring	Matched biller name (if identified)
bill_amountnumber	Extracted bill amount (if found)
due_datestring	Extracted due date (if found)
received_atstring	ISO 8601 timestamp when the email was received

The Email Message object

{
  "id": "msg_abc123",
  "user_id": "user_456",
  "from": "billing@electric-company.com",
  "subject": "Your April bill is ready",
  "biller_id": "sb_utility",
  "biller_name": "Sandbox Utility",
  "bill_amount": 142.50,
  "due_date": "2026-04-15",
  "received_at": "2026-04-01T08:30:00Z"
}

POST/v1/emails/gmail/oauth-sessions

Create a short-lived, client-authenticated Gmail PKCE transaction. Retain the verifier on your server and redirect the user to the returned consent URL.

Request body

user_id*string	User identifier in your client namespace
redirect_uri*string	Allowlisted client callback URI
code_challenge*string	Base64url SHA-256 digest of the verifier
code_challenge_method*string	Must be S256

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

cURL

curl -X POST https://sandbox.api.billerapi.com/v1/emails/gmail/oauth-sessions \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user_456","redirect_uri":"https://your-app.com/oauth/gmail","code_challenge":"<43-char-S256-challenge>","code_challenge_method":"S256"}'

Response

{ "data": { "session_id": "...", "status": "INITIATED", "oauth_url": "https://accounts.google.com/..." } }

POST/v1/emails/gmail/oauth-sessions/{session_id}/complete

Complete an authorized transaction using the one-time fragment proof and original verifier. A 202 response is durable but still processing; honor Retry-After and poll status_url.

Request body

user_id*string	Same client-scoped user identifier used to create the transaction
completion_token*string	Proof from the client redirect fragment
code_verifier*string	Original PKCE verifier

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

cURL

curl -X POST https://sandbox.api.billerapi.com/v1/emails/gmail/oauth-sessions/$SESSION_ID/complete \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user_456","completion_token":"<fragment-proof>","code_verifier":"<original-verifier>"}'

Response

{ "data": { "session_id": "...", "status": "COMPLETED", "connection_id": "...", "discovery_run_id": "..." } }

GET/v1/emails/gmail/oauth-sessions/{session_id}

Read the client-owned safe transaction projection. It never returns state, provider code, PKCE material, completion proof, or provider tokens.

Query parameters

user_id*string

Same client-scoped user identifier used to create the transaction

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

cURL

curl "https://sandbox.api.billerapi.com/v1/emails/gmail/oauth-sessions/$SESSION_ID?user_id=user_456" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

Response

{ "data": { "session_id": "...", "status": "CLAIMED", "expires_at": "..." } }

GET/v1/emails

List discovered email messages for a user. Returns emails that have been scanned and matched to billers, with extracted bill data when available.

Query parameters

userId*string	Filter by user ID
startDatestring	ISO 8601 start date filter
endDatestring	ISO 8601 end date filter
limitinteger	Maximum results to return (default: 20, max: 100)
cursorstring	Pagination cursor from previous response

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

curl "https://sandbox.api.billerapi.com/v1/emails?userId=user_456&limit=20" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

Response

{
  "messages": [EmailMessage],
  "cursor": "eyJsYXN0X2lkIjoibXNnXzEyMyJ9"
}

Was this page helpful?