Create a UtilityAPI account and obtain an API token; use it as a Bearer token in the Authorization header for all requests.
Generate an authorization form URL via POST /api/v2/forms, specifying the utility, template settings, and a callback URL; send this URL to the customer so they can authorize data sharing with their utility.
Poll GET /api/v2/authorizations or listen for a webhook callback to detect when the customer completes authorization; the authorization object will contain a UID needed for subsequent data requests.
Request bill data via GET /api/v2/bills?authorizations=<AUTH_UID> and interval data via GET /api/v2/meters/<METER_UID>/intervals to retrieve historical consumption.
For ongoing data collection, use UtilityAPI's webhook or scheduled collection features to receive new bills and interval data as the utility makes them available.
Known gotchas
Utility data availability varies widely: some utilities provide 15-minute interval data going back years; others only provide monthly bill totals — do not assume sub-hourly or even daily granularity until confirming with the specific utility's capability list.
Authorization completion can take minutes to days depending on the utility's OAuth flow or scraping mechanism; designing synchronous flows that expect immediate data after form submission will fail — always use async/webhook patterns.
Interval data is returned in the utility's local time zone without always making DST transitions explicit; failing to apply the correct timezone offset when aggregating intervals leads to off-by-one-hour errors around clock changes.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp