Overview

Our goal is to make UtilityAPI as simple as possible to both use as a website and integrate your apps, tools, platforms, backends, potatoes, etc. Getting utility bill and usage data should be an instant and effortless experience!

This documentation describes how to interact with our API. Below are sections for authorization, data formats, and API endpoints. Hopefully, by the time you're through here, you will have your black-belt in UtilityAPI-fu.

Documentation Sections

Quickstart - How to get started using the API
Terminology - What different terms we use mean
Authentication - How to use API keys
Availability - Data updates and rate limits
Formats - Common data formats you will see
Authorization Forms - Docs about the customer-facing authorization form
Green Button - Docs about our compatibility with the Green Button standard
Webhooks - How to receive notifications when an event happens
Utilities - Docs and information for each utility we support
API Endpoints - Official API endpoint documentation
- /templates - The base formatting object for our authorization forms
- /forms - Individual authorization forms that you can send to utility customers
- /authorizations - Submitted authorization forms by utility customers
- /meters - The utility services (e.g. meters) for an authorized utility customer
- /bills - The utility bills for an authorized utility customer
- /intervals - The meter usage intervals for an authorized utility customer
- /files/... - Raw or formatted data linked to by other objects in the API
- /events - Webhook events that are created during authorization and data collection
- /accounting/... - API endpoints for accounting information
  - /billing-accounts/ - The billing accounts for an authorized utility customer
  - /billing-summaries/ - The billing summaries for an authorized utility customer

Example Usage

# Create a blank form (returns form_uid 1234)
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/forms'

# Simulate someone submitting an authorization (returns referral_code ABCDEFG)
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"utility": "DEMO", "scenario": "residential"}' \
    'https://utilityapi.com/api/v2/forms/1234/test-submit'

# Get Authorizations and Meters associated with the referral code (includes meter_uid 44445555)
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/authorizations?referrals=ABCDEFG&include=meters'

# Activate the meter to collect historical data
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"meters": ["44445555"]}' \
    'https://utilityapi.com/api/v2/meters/historical-collection'

# Download bills for the meter
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/bills?meters=44445555'