Discover Billers from Email

Connect a user's Gmail account to automatically discover which billers they interact with, based on billing emails in their inbox.

How it works

1. 1Your app redirects the user to Google's OAuth consent screen using the URL from POST /emails/gmail/oauth-url.
2. 2After the user grants access, call POST /emails/gmail/connect to connect their Gmail.
3. 3BillerAPI scans their emails and matches senders to known billers.
4. 4Retrieve discovered billers via GET /emails/messages.

Step 1: Get OAuth URL

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

Step 2: Connect Gmail

After the user completes OAuth and is redirected back to your app, connect their Gmail:

curl -X POST https://sandbox.api.billerapi.com/emails/gmail/connect \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -d '{"user_id": "user_123", "client_id": "your_client_id"}'

Step 3: Retrieve Discovered Billers

curl "https://sandbox.api.billerapi.com/emails/messages?userId=user_123&limit=50" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"

Search the biller catalog

Email discovery is one way to find billers. If you already know the biller by name, search the catalog directly with GET /billers?search_term= — no Gmail connection required. Use it to power a “find your biller” typeahead before you start a link session.

curl "https://sandbox.api.billerapi.com/v1/billers?search_term=electric&status=ACTIVE" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY"