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": "test_electric_company",
  "biller_name": "Test Electric Company",
  "bill_amount": 142.50,
  "due_date": "2026-04-15",
  "received_at": "2026-04-01T08:30:00Z"
}

POST/emails/gmail/oauth-url

Generate a Gmail OAuth URL to initiate the email connection flow. No authentication required. Redirect the user to the returned URL to begin Gmail authorization.

Request body

user_id*string	Your internal user identifier
client_id*string	Your BillerAPI client ID
redirect_uristring	URL to redirect after OAuth (defaults to your configured redirect URI)

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

curl -X POST https://sandbox.api.billerapi.com/emails/gmail/oauth-url \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_456",
    "client_id": "client_xyz",
    "redirect_uri": "https://your-app.com/callback"
  }'

Response

{
  "oauth_url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}

POST/emails/gmail/connect

Complete the Gmail connection after the user has authorized via OAuth. No authentication required (this is a public endpoint). Call it after receiving the OAuth callback, passing the authorization code Google returned to your redirect URI.

Request body

user_id*string	Your internal user identifier
client_id*string	Your BillerAPI client ID
code*string	The OAuth authorization code returned to your redirect URI by Google

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

curl -X POST https://sandbox.api.billerapi.com/emails/gmail/connect \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_456",
    "client_id": "client_xyz",
    "code": "4/0Adeu5..."
  }'

Response

{
  "connected": true,
  "email": "user@gmail.com",
  "user_id": "user_456"
}

GET/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/emails?userId=user_456&limit=20" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

Response

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

Was this page helpful?