Sync Meter Inventory (V2)

The Leap meter, identified by its unique meter_id, refers to the asset where dispatch event performance measurement occurs and ultimately where revenue is generated from. Note that Leap provides access to programs that dispatch and measure performance for either the utility meter or individual device.

Information about these meters on the Leap platform is broken down into the two endpoint groups outlined below. Some of this meter and enrollment detail can also be found on the Meters tab in the Partner Portal.

🚧

Meters API V1 Deprecation

Meters API v1 endpoints (Get Meter | Search Meters) outlined in this previous developer guide will be supported through July 2025.

For a summary of field name and location changes from V1 to V2, see this changelog post.

Meter Details Endpoints

These endpoints provide data about the customer, site, utility and device, data that does not typically change, in a universal data structure across both utility- and device-type meters. Depending on the market or program this data may be supplied by the utility, program operator, or directly by the partner. Depending on the program and type of meter, many fields may be empty.

• Get Meter Details - retrieve for a single meter_id
• Search Meter Details - search all meters

Optionally, sync this data to your internal systems.

Meter Enrollment Endpoints

These endpoints provide statuses and fields related to program enrollment, which are likely to change more frequently than the meter details data above. Included in these endpoints are global and per-program enrollment statuses, participation statuses, program delivery period dates and deadlines, market group assignments, and partner actions required.

• Get Meter Enrollment - retrieve for a single meter_id
• Search Meter Enrollments - search all meters

It is important to sync your Leap meter enrollment inventory with your internal systems in order to ensure readiness for dispatch events and increase successful meter enrollments. Key use cases and fields to store are outlined in the sections below.

Polling Search Meter Enrollments

Keeping data up to date requires polling the Search Meter Enrollments endpoint at least once per day as some of these statuses can change daily. You can also use the last_modified_date_time request body parameter to retrieve only meters that have been updated since you last polled. There is an extensive list of other request body parameters that can be used to tailor your calls and filter for only the list of meters that you are looking for.

📘

Webhook events for these use cases will be coming in 2025.

Meter Updates & Last-Modified Search Parameter

Any field value in the meter enrollment response that is updated (from one value to another, from null to a value, or from a value to null) will trigger an update (updated_at timestamp will change) so that this meter will now show up when using the last_modified_date_time request body parameter.

Updates within the program_enrollment array:

• The first time delivery period objects are added (for any new program) triggers an update
• For an existing delivery period object, all fields are static except enrollment_status, market_group_id, and market_group_name. If any of these fields change, this triggers an update.
• When a meter rolls over from one delivery period to the next (e.g. beginning of each month in CA CCA program), this will NOT trigger an update unless one of the fields noted above changes on that date

Updates within the required_actions object:

• If an action code object is added or removed (action was resolved) from either the partner or leap arrays this will trigger an update
• Once an action code object is present, all fields are static within that object except delivery_period and enrollment_deadline_date_time. When either of these fields change (by rolling over to the next deadline date and/or delivery period because the action has not yet been resolved), this will NOT trigger an update.

Key Meter Enrollment Use Cases

The remainder of this guide outlines key use cases and data to store internally from the Search Meter Enrollments endpoint responses. These are broken down into two categories: 1) ensuring readiness for dispatch events and 2) optimizing enrollments.

Ensure readiness for dispatch events

Use Case A: Store Leap meter_id in your internal systems

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 dispatching and other automation use cases. For dispatching, the applicable meter IDs are included in the dispatch notifications so you know which assets to schedule the events for.

Storing the Leap meter ID is typically a 3-step process:

1. Filter for unknown or newly created meter IDs (using the created_after_date_time or last_modified_date_time request body parameters)
2. Correlate each meter ID to the appropriate customer or site ID in your systems using the partner_reference value. This is the partner-provided refId appended to Leap Connect authorization URLs or the unique reference ID set during the Partner-Created Meters process for programs that support this.
3. Use the meter_type field in the response to determine how to store each meter ID as this could vary depending on the program and whether the meter ID is referencing a utility_meter or a device. Review the Utility Meters vs. Devices guide for more details and recommendations.

{
  "meter_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partner_reference": "unique-reference-id-12345",
  "meter_type": "UTILITY_METER",
  ...
}

Reference ID Considerations:

• Missing or duplicate reference IDs
  For customer-authorized meters using Leap Connect, it is possible that the refId parameter was not included (in which case the partner_reference would be empty) or that a customer authorized multiple meters using the same Leap Connect link (in which case multiple meters would have the same partner_reference). In these cases you must use the Meter Details endpoint (Get | Search) to use other information about that meter (e.g. customer name, address, utility account number) in order to correlate to your appropriate customer or site ID.
• Setting or overwriting reference IDs
  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. You can set or modify these partner_reference values at any time via the partner portal or using the meter reference ID endpoint.

Use Case B: Track meter enrollment status

Program enrollment requires both eligibility and enrollment checks to be completed before a meter can be determined “ELIGIBLE” and eventually “ACTIVE” in a program. The status of these checks is summarized by the global_enrollment_status and per program enrollment_status fields. For more information on the meter status values and their typical progression take a look at the Meter Status Guide in our Knowledge Center.

Along with the meter_idandmeter_type, you’ll also want to store the global and/or program-level enrollment statuses and ensure that any meters with an “ACTIVE” enrollment status are fully ready to be dispatched. If the meter is “ACTIVE” in at least one program, then it will also have an “ACTIVE” global_enrollment_status.

{  
    "global_enrollment_status": "ACTIVE",  
    "program_enrollment": [  
      {  
        "program_identifier": "CEC-DSGS",  
        "delivery_period": "CEC-DSGS_2024_AUG_OCT",
        "enrollment_status": "ACTIVE",
        ...
      }
   ]
}

📘

Active Enrollment Status for Future Delivery Periods

Once a meter has all of its eligibility and enrollment checks completed and has been added to a market group for an upcoming (future) delivery period, its enrollment_status will switch to “ACTIVE” for that upcoming delivery period.

Use Case C: Optionally sync market group mapping (only if dispatching in groups)

When participating in a program, meters are aggregated by Leap into market groups. If you have an internal system that must dispatch your assets at an aggregated group level, it is important to sync your inventory to Leap's market group assignments.

For any current and upcoming delivery periods within the program_enrollment array, make sure to track any changes to the market_group_id for each meter ID. You will need to align your internal meter-to-group mapping to match what Leap is providing in this array for each delivery period indicated by the start and end times.

{
  "program_enrollment": [
    {
      "program_identifier": "CCA",
      "delivery_period": "CAISO-CCA_2024_OCT",
      "delivery_period_start_date_time": "2024-10-01T07:00:00.000Z",
      "delivery_period_end_date_time": "2024-11-01T07:00:00.000Z",
      "market_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "market_group_name": "GRP1_NAME",
      ...
    }
  ]
}

❗️

Dispatching in Groups

If your device management platform must dispatch in groups, it is essential that you keep your inventory in sync. Dispatching a group with outdated group assignments can cause poor dispatch performance and reduce grid services revenues.

Optimize enrollments

Use Case D: Trigger follow-ups on partner required actions

Most meters progress through the enrollment process into an “Active” status 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. Required actions only apply to intended programs that are assigned for your meters, not for all programs offered by Leap.

If a partner action is required on a meter, these will be listed within the partner array of the required_actions object. An example is listed below. For more details on the list of eligibility and enrollment checks, their associated action or status code, and the next step to take to resolve each of them (including customer email/notification templates), check out the Eligibility and Enrollment Overview guide.

It is recommended to automate the next step whenever possible (e.g. sending notification to customer requesting action or triggering an alert for an operations team member when non-customer actionable or automatable).

{
  "required_actions": {
    "partner": [  
      {  
        "program_identifier": "CCA",  
        "delivery_period": "CAISO-CCA_2024_NOV",  
        "enrollment_deadline_date_time": "2024-10-15T07:00:00.000Z",  
        "action_type": "NOT_ENROLLED_IN_CONFLICTING_PROGRAM",  
        "action_description": "This meter must be disenrolled from a conflicting program: PG&E, ART. Learn more in our partner guide.",  
        "action_code": "MRKT_0002"  
      }  
    ]
  }

Use Case E: Track partner-defined participation status

Meters start in “Participate” status by default but occasionally you may need to “Idle” the meter (e.g. device down or customer not participating for a particular season) or “Disenroll” the meter completely if the customer requests to be removed from the program. Check out the Participation Status Knowledge Center guide for more details on these statuses.

It is a best practice to store this participation status schedule internally so you know when a meter may no longer be participating and can update that appropriately if required. The example below shows a participation period, followed by a two-month idle period, and then an indefinite participation period.

{
  "participation_preferences": [  
    {  
      "participation_preference": "PARTICIPATE",  
      "start_time": "2024-11-01T07:00:00Z",  
      "end_time": "2025-04-01T07:00:00Z"  
    },  
    {  
      "participation_preference": "IDLE",  
      "start_time": "2025-04-01T07:00:00Z",  
      "end_time": "2025-06-01T07:00:00Z",  
      "reason": "Idle Time"  
    },  
    {  
      "participation_preference": "PARTICIPATE",  
      "start_time": "2025-06-01T07:00:00Z",  
      "end_time": "9000-01-01T00:00:00Z"  
    }  
  ]
}

Use Case F: Track program delivery period dates & deadlines

The program_enrollment array provides current and next two delivery period details for all intended programs that are assigned to a meter. The example below shows these three delivery periods for a single program on a currently Active meter. Contact Leap at [email protected] to update your intended program settings if you are not seeing any program information or would like to see different programs.

Tracking delivery period dates and deadlines for each program will help you optimize your enrollments by ensuring marketing campaigns are scheduled appropriately and meters are onboarded and eligible ahead of enrollment deadlines.

{
  "program_enrollment": [
    {
      "program_identifier": "CCA",
      "delivery_period": "CAISO-CCA_2024_OCT",
      "delivery_period_start_date_time": "2024-10-01T07:00:00Z",
      "delivery_period_end_date_time": "2024-11-01T07:00:00Z",
      "enrollment_status": "ACTIVE",
      "enrollment_deadlines": [
        {
          "enrollment_deadline_date_time": "2024-09-29T07:00:00Z",
          "activation_date_time": "2024-10-01T07:00:00Z"
        },
        {
          "enrollment_deadline_date_time": "2024-10-13T07:00:00Z",
          "activation_date_time": "2024-10-15T07:00:00Z"
        }
      ],
      "market_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "market_group_name": "PGEB_2_PDRP96"
    },
    {
      "program_identifier": "CCA",
      "delivery_period": "CAISO-CCA_2024_NOV",
      "delivery_period_start_date_time": "2024-11-01T07:00:00Z",
      "delivery_period_end_date_time": "2024-12-01T08:00:00Z",
      "enrollment_status": "ELIGIBLE",
      "enrollment_deadlines": [
        {
          "enrollment_deadline_date_time": "2024-10-30T07:00:00Z",
          "activation_date_time": "2024-11-01T07:00:00Z"
        },
        {
          "enrollment_deadline_date_time": "2024-11-13T08:00:00Z",
          "activation_date_time": "2024-11-15T08:00:00Z"
        }
      ],
      "market_group_id": null,
      "market_group_name": null
    },
    {
      "program_identifier": "CCA",
      "delivery_period": "CAISO-CCA_2024_DEC",
      "delivery_period_start_date_time": "2024-12-01T08:00:00Z",
      "delivery_period_end_date_time": "2025-01-01T08:00:00Z",
      "enrollment_status": "ELIGIBLE",
      "enrollment_deadlines": [
        {
          "enrollment_deadline_date_time": "2024-11-29T08:00:00Z",
          "activation_date_time": "2024-12-01T08:00:00Z"
        },
        {
          "enrollment_deadline_date_time": "2024-12-13T08:00:00Z",
          "activation_date_time": "2024-12-15T08:00:00Z"
        }
      ],
      "market_group_id": null,
      "market_group_name": null
    }
  ]
}

🚧

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 gracefully handle new fields added to these JSON objects.