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.

  • 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
# 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'