Plug guide

Get your users’ utility statement data

What is Plug?

Plug represents a collection of API endpoints and webhooks that provide your users' utility statement & interval data in a standardized format from over 125 utility providers across the United States.

Your users' most recent statements are made available, as well as historical statement data ranging from 12-24 months in the past. Using Plug, you can easily retrieve how much energy your user used for a given statement period, how much was billed, which tariff was applied, and more.

In addition, if a utility provider records interval usage data through smart meters, Plug makes that data available in the resolutions provided by the utility.

What do I need to do to get ready for Plug?

  • Verify that your users' utility providers are supported by Arc. You can see a complete list of utility providers supported in this table.
  • Integrate Connect, which gives you access to your user's utility provider data. For more information, see the Connect overview documentation.
  • Understand how to get information on your user's utility account as well as how to verify when (and whether) statement and interval data is available. See Arc basics.

How it works

What is the best way to get information with Plug?

With Plug, you can be notified of events and updates for your users' account, statement, and interval data via webhook message. You can then pull the data that is the subject of the message.

It's recommended that you listen for webhook messages and use the API to get only that data that is referenced in the message. However, you can poll Plug's APIs if you prefer.

Getting Statement Data

What statement data is available with Plug?

For each statement, Plug gives you access to the following data in a standardized format:

Note: Not all fields are available for each utility.

Field NameField Description
idArc's unique ID for the given statement
client_user_idThe unique identifier for the user that the statement belongs to
tariffInformation about the tariff related to the statement
utility_nameThe name of the utility that issued the statement
utility_account_idArc's unique ID for the utility account that the statement pertains to
statement_dateThe date the statement was issued
due_dateThe date a payment for the statement is due
service_start_dateThe beginning of this statement period
service_end_dateThe end of this statement period
kwhThe amount of energy, in kilowatt hours, used during the statement period
utility_chargeThe total charge, in USD, for all line items on the bill that the consumer is responsible for, including electric and gas charges if this account has multiple service types
supplier_chargeThe charge, in USD, for the electricity supply from the user's electricity supplier (either retail electricity provider or CCA), if not supplied by the utility
supplier_account_idThe unique identifier for this utility account that retail suppliers must provide to the utility to change an end-user's supplier
gas_chargeAny charges for gas services on the bill
past_dueA boolean field (true/false) indicating whether there are overdue payments on the bill
created_atThe date the statement was created in Arc's system
updated_atThe date the statement was last updated in Arc's system
sandboxedIf the statement relates to a sandbox account with Arc's system - an account that was created with sandbox API keys (true/false)
pdf_urlAn address where a PDF of the statement can be accessed (expires after 10 minutes to ensure the protection of user personal information)
final_billTrue/false indicator of whether this statement is the final bill of service for an account
total_countShows you the total count of statements returned. Arc will never return more than 100 statements at a time

Knowing when statement data is available for newly connected user

Plug starts gathering statement data for connected users after accounts are discovered as a part of Arc's Connect flow. Plug will gather at least 12 months' worth of statement data, if that data exists.

When Plug is finished gathering existing statements for an account, it will post the Historical Utility Statements Discovered webhook message. The body of this message contains the number of statements gathered along with all of the available data for those statements. You will also receive a Utility Account Updated webhook message with utility_statements set to AVAILABLE in the feature availability map.

If you are polling the API for statement data availability instead of listening for webhooks, you can:

  • Use Get Utility Account and watch for the value of utility_statements in the feature availability map to change to AVAILABLE.
  • Use List Utility Statements which takes an account ID and returns all statements if they are available.

Getting statement data

Using the Plug API, you are able to retrieve statement level data through two different endpoints:

  • List Utility Statements: This endpoint takes a user's client_user_id or utility_account_id and returns all available statements. If client_user_id is provided as a query parameter, statements for all of that user's accounts will be returned in a single object. If utility_account_id is used instead, only statements for the specified account will be returned.
    • The optional limit parameter controls how many statements are returned
    • The optional updated_after and updated_before parameters control the statements that are returned by their updated_at date. These parameters are also used to traverse paginated responses.
    • The optional order parameter controls if the statements are ordered ascending or descending according to their updated_at timestamp. The default is descending.

Screen_Shot_2022-06-29_at_4.45.06_PM.png

  • Get Utility Statement: This endpoint returns a single statement based on the utility_statement_id provided from the List Utility Statements endpoint above.

Finding out when new statements are posted

Plug checks accounts for new statements every month. The day after the utility provider posts a new statement, Plug will let you know via a New Utility Statement Available webhook message. You can also use the List Utility Statements request and filter all of the statements returned for the most recent.

Getting Interval Data

Which interval data is available with Plug?

You can see a current list of utility providers that Arc supports interval data for in this table.

The interval data provided by Plug is based on the resolution of the data provided by the utility (15, 30, 45 minutes, hourly, etc.).

The Plug API returns the following fields for each batch of interval data:

Field NameField Description
client_user_idUnique ID for the user this Utility Statement is associated with. Provided by your application when the user goes through Connect
utility_account_idThe unique ID associated by Arc to the Utility Account that this Utility Interval was created for
intervals_earliest_timeThe timestamp of the earliest interval record Arc has for this Utility Account
intervals_latest_timeThe timestamp of the latest interval record Arc has for this Utility Account
batch_start_timeThe timestamp of the earliest interval record returned in the interval data included in this request
batch_end_timeThe timestamp of the latest interval record returned in the interval data included in this request
dataA list of all the interval records. A description of the data fields are in the table below

Here is a list of the fields that are nested within the data object for each interval data request. These fields represents the actual interval usage data:

Field NameField Description
start_timeThe start time of this interval record
end_timeThe end time of this interval record
kwhThe actual amount of energy usage in this interval, in kilowatt-hours
is_null_kwhIf true and kwh is 0, then the usage for the given period is null, indicating a gap in the usage data. If false and kwh is 0, then the reading represents a net energy usage of 0 kwh.

Getting interval data for newly connected users

Plug starts gathering interval data (if supported) for connected users after accounts are discovered.

The quickest way to find out if any interval data is available for a particular account is to listen for the Utility Account Updated webhook message. If Plug is finished looking for interval data and there is none on file, utility_intervals will be set to NOT_AVAILABLE.

When Plug is finished collecting interval data for an account, it will post a Historical Utility Intervals Discovered webhook message.

If you are polling the API for interval data availability, you can

  • Use Get Utility Account and watch for the value of utility_intervals in the feature availability map to change to AVAILABLE.
  • Use List Utility Intervals which takes an account ID and returns all intervals if they are available.

Getting interval data

Using the Plug API, you can retrieve interval data by using the following endpoint:

  • List Utility Intervals: This endpoints takes a utility_account_id and returns all available interval data, limited by the optional parameters start_time and end_time.

Screen_Shot_2022-06-29_at_4.48.57_PM.png

Finding out when new interval data is available

Whenever you want to refresh interval data, make the List Utility Intervals request, which takes the account ID as its sole parameter. There is currently no webhook for the discovery of new interval data.

For more information...