Sync Meter Inventory (V1)
Meters API V1 Deprecation
Meters API v1 endpoints outlined in this guide will be supported through July 2025. Please use the new v2 endpoints outlined in this Meters API v2 developer guide.
For a summary of field name and location changes from V1 to V2, see this changelog post.
Integrate and Sync a Meter Portfolio
Meters are the basic units of inventory providing grid services with Leap. Meters represent your end customers and the devices sitting behind the utility meter which will enroll in grid services programs to unlock revenue and support the grid by responding to dispatches.
Each meter contains a unique, Leap assigned, meter_id along with metadata about the meter coming from the grid operator (e.g. transmission region), utility (e.g. customer, address, account number, tariff) and Leap (e.g. enrollment status, participation status).
You'll want to sync some of this meter metadata with your internal systems on an ongoing basis. Which data to sync depends on what you are trying to accomplish but the common scenarios are outlined in this guide below.
This meter metadata can be seen within the Partner Portal which includes a CSV bulk download option but doing this manually can be time consuming, error-prone, and difficult to scale. In order to automate this, you can use the 2 API endpoints below.
- Search Meters - Queries all meters or all meters added within a date/time range
- Get Meter - Queries an individual meter_id
Polling Frequency
Polling the Search Meters endpoint on a frequent basis (e.g. daily) is recommended in order to check for new meter updates. You can also use the
date_last_modifiedbody parameter to retrieve meters that have had any updates to their status or metadata since the last time you queried.
New Fields in Endpoint Responses
New fields may be added to these API endpoint responses as additional meter metadata becomes available. These additional fields are not considered breaking changes and therefore would be released under the current API version so it is important to ensure your implementation can handle gracefully new fields added to these JSON objects.
What to Look for in the Meter Metadata
The scenarios below outline where to look for updates in the meter metadata and the steps to maintain an updated inventory of meters with the correct synchronization of meter states between Leap and your system(s). Depending on your integration goals you may not need to sync updates for all of these scenarios.
Connect Leap Meter IDs to Your Customer/Site or Device IDs
As noted above, each meter has its own unique meter_id. Connecting this to your own customer or site IDs and storing this in your internal systems is important for additional automation use cases. For example, when dispatching, the applicable meter IDs are included in the dispatch notifications.
Utility Meter vs. Device Programs
How you store the Leap meter ID in your internal database varies depending on the program and whether the meter ID is referencing a
utility_meteror adevice. Review the Utility Meters vs. Devices guide for more details.
Meter vs. Group Dispatching
If your event management system dispatches in groups of meters or devices, check out the Update Meter Group Mapping section below to make sure your meter groups stay in sync with Leap's groups.
When connecting meters to Leap using the Leap Connect authorization process, it is recommended to append to the end of each registration URL a unique customer identifier using the refId query string attribute. If this is specified, it will automatically be included as the partner_reference value in the meter metadata. You can use this partner_reference to create a relationship with assets in your internal inventory.
{
"meter_id": "f5bfd5fa-87fd-444b-98ad-bef6cdbd5c59",
"partner_reference": "meter1",
...
}
Additional Reference ID Considerations:
- If a customer authorizes multiple meters during one Connect authorization session, the
partner_referencewill be the same for all of those meters. - Once the
partner_referencefield is populated for a meter, it will not get overwritten if the customer re-authorizes the meter with a different RefId query parameter. - You can modify these
partner_referencevalues at any time via the partner portal or using the meter reference API endpoint
Track New Meter Authorizations
Meters are created and added to the platform following successful end-customer authorization. In order to check for new meters since the last time you polled Search Meters, you can make the request query using the date_added_from and date_added_to or date_last_modified body parameters. This will return only meters which were added to the platform during that date/time window.
{
"date_added_from": "2022-01-12T21:12:46.784Z",
"date_added_to": "2022-05-25T21:12:46.784Z"
}
Monitor Market Enrollment
In most markets, meters must be formally enrolled into the market in order for the meter to become Active on the Leap platform and be ready for and approved prior to participation. The enrollment status value indicates where in the market enrollment process a meter is. For more information on the meter status values and their typical progression take a look at this Meter Status Guide in our Knowledge Center.
Active Meters
Ensure that any meter with an "Active" status is now able to receive dispatch events in your device and event management system.
"enrollment": {
"status": "Active",
"active_periods": {
...
}
Check for Meters Requiring Partner Action
Most meters progress through the enrollment process into an “Active” state without any issues but some meters may require additional actions to be taken by Leap or you as the partner to make the meter eligible for participation. If a partner action is required on a meter, the action_required field will be true and the status_reasons array will include one or more partner actionable status codes and an associated comment or explanation.
For a list of the possible status codes, check out the Status Codes section of the Meter Status Guide in our Knowledge Center. This guide also contains the suggested partner action for each code and links to email templates you can use to automate outreach to the impacted customers in order to try and get the issue resolved.
"enrollment": {
"status": "Ineligible",
"status_reasons": [
{
"code": "MRKT_0002",
"comment": "The meter needs to dis-enroll from another program: Contract is on SEP. For more information, please contact [email protected]."
}
],
"action_required": true
}
Update Meter Group Mapping (if dispatching in groups)
When participating in the market, meters are aggregated into groups. If you have an internal system that manages and dispatches your assets at an aggregated or group level, it is important to sync your inventory against Leap's group assignment.
Grouping is denoted using market_group_id or market_group_name in the participation array which provides assignment for the current and upcoming 2 days. These group assignments can change over time so it is recommended to check this participation object daily to look for upcoming market_group_id or market_group_name changes.
"participation": [
{
"market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
"market_group_name": "PGF1_2_PDRP79",
"program_name": "DRAM",
"trade_date": "2022-06-02T07:00:00Z"
},
{
"market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
"market_group_name": "PGF1_2_PDRP79",
"program_name": "DRAM",
"trade_date": "2022-06-03T07:00:00Z"
},
{
"market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
"market_group_name": "PGF1_2_PDRP79",
"program_name": "DRAM",
"trade_date": "2022-06-04T07:00:00Z"
}
]
Program Names
Program names used in this
participationobject do not always match the program name used in the dispatching service.
Group Dispatching
If you are using group dispatches, it is essential that you keep your inventory in sync. Dispatching a group with outdated assignments can cause poor dispatch performance and reduce grid services program revenues.
Updated about 2 months ago