Sync Meter Updates

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.

🚧

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 IDs

As noted above, each meter has its own unique 'meter_id'. Connecting to this 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.

📘

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.

As part of the Leap Connect customer authorization flow, 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_reference will be the same for all of those meters.
  • Once the partner_reference field is populated for a meter, it will not get overwritten if the customer re-authorizes the meter with a different RefId query parameter. However, coming soon, a partner may override or edit this value directly for each meter if needed.

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 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_from": "2021-05-19T07:00:00Z",
    "active_to": "2021-12-31T08:00:00Z",
    "eligible_from": "2021-05-19T07:00:00Z",
    "eligible_to": "2029-01-02T08:00:00Z",
    "status_reasons": [],
    "partner_preferred_action": "Participate",
    "partner_indicated_idle_period": null,
    "partner_indicated_disenrollment": null
}

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. These actions are indicated in the status_reasons array and they will correspond to an “ActionRequired” meter status when querying these meters via the API.

For a list of the possible status reasons check out the Status Codes section of the Meter Status Guide in our Knowledge Center. This guide indicates which codes require partner action and which codes Leap is working to resolve. Occasionally it will be required to reach back out to your customer to address the issue and this guide will also link to email templates you can use in these cases.

"enrollment": {
    "status": "ActionRequired",
    "active_from": null,
    "active_to": null,
    "eligible_from": null,
    "eligible_to": null,
    "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]"
           }
     ],
    ...
    }

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 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' changes.

"participation": [
    {
      "market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
      "trade_date": "2022-06-02T07:00:00Z"
    },
    {
      "market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
      "trade_date": "2022-06-03T07:00:00Z"
    },
    {
      "market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
      "trade_date": "2022-06-04T07:00:00Z"
    }
]

🚧

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.


What’s Next