1. Documentation
2. Suppliers

Suppliers

Solution Eligibility

This solution is only available to Massachusetts-licensed suppliers and municipal aggregators.

Solution Overview

Suppliers and municipal aggregators (“Suppliers”) need timely access to their customers' interval data for a variety of use cases including bill verification, analytics, and customer experience.

As a part of their Massachusetts smart meter deployments, some utilities are offering a Bulk Data Exchange solution, powered by UtilityAPI, to deliver post-validation, estimation, and editing (VEE) revenue-quality 15-minute or 5-minute interval data for all of a supplier's customers with AMI meters on a daily basis, within 48 hours of processing. Interval data fields, example API response, and change events handling are detailed below.

Suppliers' Electronic Data Interchange (EDI) transactions and this Bulk Data Exchange (BDX) solution are complementary. Suppliers should expect to continue to receive their customers' account and billing summaries data from their existing EDI integrations.

This solution (BDX) will deliver interval data for suppliers' current customers where the supplier is the supplier of record for a given Electric Distribution Company's (EDC) accountID in the respective EDC's system. Interval data sharing is opt-out, meaning that a customer's interval data will be shared with an approved supplier unless the customer explicitly opts out of, or revokes, their interval data sharing authorization with their supplier. See “Customer opts out of interval data sharing via utility's Data Sharing Portal” below.

The following events impact a customer's interval data sharing with a supplier, similar to existing EDI processes.

Getting Started

For New Supplier Users

You must have a UtilityAPI account in order to use this solution. While you only need one UtilityAPI account, you must register with each EDC you want your customers' interval data for.

Below is a summary of the UtilityAPI account creation and EDC registration experience.

Once you've successfully submitted your enrollment for access, you will be redirected to this API documentation where you can begin developing your API integration using the API Reference and its mock data.

At this time, your registration will be pending approval by the EDC. You can create API tokens, however, it will not allow you access to any of your customer data until the EDC updates your registration status to “Approved”. You can check the status of your registration in settings.

In order to approve your registration, the EDC will verify that the registering user is a valid employee or representative of the approved and licensed supplier selected from the dropdown during the registration process. If for any reason the EDC is unable to approve your registration, it will send you an email to the email address associated with your registration describing the issue.

You can view and manage your registration status. You will receive an email notification once your registration has been reviewed by the EDC.

Once your registration is approved, your API token will grant you access to the API where you can retrieve your customers' daily interval files.

Upon approval, the next day's set of files will be available and subsequent days' files will be generated each day forward as long as your registration remains in good standing.

Ongoing workflow

API Reference

Authentication

All endpoints require an API token. You must include the API token in the Authorization header using the Bearer format. You can generate an API token in your user settings in the UtilityAPI Dashboard.

Endpoints

GET /api/v3/suppliers/files

Returns download links for bulk data files for a given utility and date.

Query Parameters

Response

Content Type: application/json

Properties:

{
    "type": "authorizations",
    "url": "string",
    "expires_at": "ISO 8601 string"
}

[
    {
        "type": "string",
        "url": "string",
        "expires_at": "ISO 8601 string"
    }
    ...
]

Examples

Example request:

curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    "https://utilityapi.com/api/v3/suppliers/files?utility=EVRSRCMA&process_date=2025-12-15"

Example response:

{
    "supplier_id": "Supplier 1234",
    "date": "2025-12-15",
    "utility": "EVRSRCMA",
    "authorizations_file": {
        "type": "authorizations",
        "url": "{presigned_url}",
        "expires_at": "2025-12-15T00:15:00Z"
    },
    "intervals_files": [
        {
            "type": "daily_intervals",
            "url": "{presigned_url}",
            "expires_at": "2025-12-15T00:15:00Z",
        },
        {
            "type": "historical_intervals_for_new_auths",
            "url": "{presigned_url}",
            "expires_at": "2025-12-15T00:15:00Z",
        }
    ]
  }

Bulk Data Files

Suppliers will request files through an API on a daily basis. There is no graphical user interface (GUI) or front-end. The API's response will include download links to intervals files.

authorizations_file

Contains the full set of a supplier's interval data sharing authorizations with their customers as of that day. It maps a supplier's customers' service points to their respective EDC accountIDs and displays the current status of each service point's interval data sharing authorization with the supplier.

If an accountID has multiple service points, there will be a row per service point.

intervals_files

The last 24 hours worth of intervals will be presented along their associated service points i.e. each interval file will contain data for multiple service points.

Interval data for each day may be split across multiple CSV files to limit overall file size.

If applicable for any given day, any newly enrolled customers' historical intervals will also be shared, including up to 24 months of interval data or however much is available.

Availability of Bulk Data

Data download links for a given date will typically become available within 72 hours of meter reads, to allow for VEE and processing. For example, December 14th's data will be ready on December 17th at the latest. We will generally be attempting to make the data available much earlier than that.

Prior to the readiness of data, the endpoint will return HTTP code 202 indicating that the user should wait and try again later.

Requestors are expected to implement scheduling, or polling, for their daily API calls. It's recommended to implement exponential backoff to gracefully handle retry events by increasing the wait time exponentially (e.g., 5 minutes, 15m, 30m, 1hr) to ensure a day's data is collected.

Lifespan of Pre-signed URLs

File download links will remain valid until the expiry time returned in the same endpoint response. The time for which a download link will remain valid is approximately 15 minutes. After expiry, the user may make another request to receive new download links.

Data Retention Period

The endpoint will accept date parameters that are within the past 30 days. After 30 days, download links for the out of range date will no longer be available and the endpoint will return HTTP code 400.

Encoding & Delimiters

CSV files will be encoded in UTF-8 and will have comma delimitters.

Daily Scenarios

Daily Interval Files

Data Order

Suppliers should read files in the order that they appear in the endpoint response. When files are read in this order, rows will be in ascending (service_point_id, date, time) order.

Duplicate Rows and Quality Flag

When there is more than one row with the same (service_point_id, date, time), the one that appears latest should be kept; hence why reading the files in order is important. This includes scenarios where the reading is estimated and is updating over time.

Example Files and Desired End State

Take for example the following truncated interval files received on December 14th:

• intervals_1.csv (Dec 14):

• intervals_2.csv (Dec 14):

And the following interval files received on December 15th:

• intervals_1.csv (Dec 15):

The files should be ingested in this order:

• intervals_1.csv (Dec 14)
• intervals_2.csv (Dec 14)
• intervals_1.csv (Dec 15)

And the reading for this service point should be understood as:

Net Metering

The Channel Type column is used for distinguishing between measured quantities such as consumption, generation, net usage, etc. These can be ingested separately as multiple channels. Alternatively, if only the net value is desired, rows with Channel Type other than NET_USAGE may be ignored.

Why Interval Data May Not Be Present

Daily interval data is only provided for active and authorized service points. If a customer:

• becomes inactive by moving out of the EDC's service territory
• switches from you being their supplier
• opts out of interval data sharing
• or opts out of having a smart meter installed

Frequently Asked Questions

Can multiple users of a supplier access the API?

A supplier company can have many users, or employees, who can use the solution. Each user can generate API tokens to be used to access data. Each set of API credentials point to the same supplier company's dataset; there is not a unique dataset per user.

For every registered supplier, all associated DUNS+4 accounts will be available to the supplier. Each registered and approved user from a supplier has access to all of that suppliers' authorized customer accounts. Authorizations are scoped to an entire account, so if an applicable change event occurs (such as a customer discontinuing their relationship with a supplier), availability of data for all service points in that account will change accordingly.

What You Receive

• A consolidated intervals dataset containing:
• All authorized service points
• Across all authorized account IDs
• For all authorized account IDs associated for all your DUNS+4

What This Means in Practice

• There are no separate folders, files, or partitions per DUNS+4.
• If you have multiple DUNS or DUNS+4, they will all be mapped to your supplier organization. You can request data for any of your DUNS
• If a customer accountID has an active authorization with your supplier organization, all of its service points' interval data will appear in your available intervals files.

How is this different from Green Button Connect?

Green Button Connect is an opt-in data sharing service for any type of third party to request consent from a utility customer to access their utility account, billing, and interval data. Whereas utility customers must explicitly grant consent, or authorization, to share their data with a select third party with Green Button Connect, this solution utilizes an opt-out model. Because suppliers have received their customers' consent to access their utility data as a prerequisite to providing them with electricity supply, it has been determined that suppliers are entitled to receive these same customers' smart meter data without additional consent. However, similar to Green Button Connect, customers are still in control of their interval data sharing so can manage, or opt-out, of interval data sharing at any time.

For suppliers, Green Button Connect may be viewed as a way to request access to prospective customers' account, billing, and interval data whereas this solution gives you access to your existing customers' interval data only.

National Grid and Eversource have Green Button Connect platforms deployed for their Massachusetts customers. Both are powered by UtilityAPI. You can be signed up for this solution and Green Button Connect at the same time. To register for Green Button Connect, click here.