The Complete Guide to Utility Bill APIs
Everything developers need to know about integrating utility bill data into their applications—architecture patterns, data models, and best practices.
Integrating utility bill data into your application opens up powerful capabilities—from automated expense management to sustainability reporting. This guide covers everything you need to know about utility bill APIs.
Understanding Utility Data APIs
Unlike traditional APIs that query databases, utility bill APIs must solve a unique challenge: extracting data from hundreds of different utility provider portals, each with their own authentication, navigation, and document formats.
The Statement Data Model
A well-designed utility bill API returns structured data that's immediately usable:
{
"id": "stmt_abc123",
"account_id": "acct_xyz789",
"provider": "pge",
"statement_date": "2024-11-15",
"due_date": "2024-12-05",
"amount_due": 234.56,
"previous_balance": 0.00,
"service_address": {
"line1": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94102"
},
"usage": {
"kwh": 892,
"billing_days": 30,
"avg_daily_kwh": 29.7
},
"charges": [
{ "description": "Electric Usage", "amount": 178.40 },
{ "description": "Delivery Charges", "amount": 42.16 },
{ "description": "Taxes & Fees", "amount": 14.00 }
],
"pdf_url": "https://api.vespine.io/v1/statements/stmt_abc123/pdf",
"created_at": "2024-11-16T08:23:45Z"
}Integration Patterns
Pattern 1: Webhook-Driven
The recommended approach for most applications. Vespine pushes data to your endpoint when new bills are available:
@app.post("/webhooks/vespine")
async def handle_webhook(request: Request):
payload = await request.json()
# Verify webhook signature
signature = request.headers.get("X-Vespine-Signature")
if not verify_signature(payload, signature):
raise HTTPException(401, "Invalid signature")
if payload["event"] == "statement.created":
statement = payload["data"]
# Process the new bill
await process_utility_bill(
account_id=statement["account_id"],
amount=statement["amount_due"],
due_date=statement["due_date"],
pdf_url=statement["pdf_url"]
)
return {"received": True}Pattern 2: Polling
For simpler integrations or when webhooks aren't feasible:
// Poll for new statements daily
const fetchNewStatements = async () => {
const since = getLastSyncTimestamp();
const response = await fetch(
`https://api.vespine.io/v1/statements?since=${since}`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { data: statements } = await response.json();
for (const stmt of statements) {
await processStatement(stmt);
}
updateLastSyncTimestamp();
};Authentication & Security
Utility bill APIs handle sensitive credentials. Here's how authentication typically works:
API Key Authentication
Bearer tokens for server-to-server calls. Keep these secret—never expose in client-side code.
Webhook Signatures
HMAC-SHA256 signatures verify webhook payloads. Always validate before processing.
Credential Encryption
Utility portal credentials are AES-256 encrypted at rest. Zero plaintext storage.
IP Allowlisting
Restrict API access to known IPs for additional security layer.
Error Handling
Utility portals are notoriously flaky. Build resilience into your integration:
| Error Code | Meaning | Action |
|---|---|---|
| CREDENTIAL_INVALID | Login failed | Prompt user to update credentials |
| PORTAL_UNAVAILABLE | Utility site down | Automatic retry in 1 hour |
| NO_BILL_FOUND | No new bill available | Normal—check again next cycle |
| RATE_LIMITED | Too many requests | Exponential backoff |
Best Practices
- Implement idempotency. Webhooks may fire multiple times. Use statement IDs to dedupe.
- Store PDFs locally. Download and store PDFs for compliance. URLs may expire.
- Handle partial data gracefully. Some fields may be null if not available on the bill.
- Monitor job status. Check sync job status to catch credential issues early.
- Use sandbox for testing. Don't test against production utility portals.