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](https://developer.leap.energy/docs/utility-meters-vs-devices).

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](https://partner.leap.energy/meters).

## 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](https://developer.leap.energy/reference/getmeterdetails) - retrieve for a single `meter_id`  
- [Search Meter Details](https://developer.leap.energy/reference/searchmeterdetails) - 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](https://developer.leap.energy/reference/getmeterenrollment) - retrieve for a single `meter_id`  
- [Search Meter Enrollments](https://developer.leap.energy/reference/searchmeterenrollments) - 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](https://developer.leap.energy/reference/searchmeterenrollments) 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.

#### 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](https://developer.leap.energy/reference/searchmeterenrollments) 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](https://developer.leap.energy/docs/dispatch-automation-v2), 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](https://developer.leap.energy/docs/leap-connect#url-query-parameters) authorization URLs or the unique reference ID set during the [Partner-Created Meters](https://developer.leap.energy/docs/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](https://developer.leap.energy/docs/utility-meters-vs-devices) guide for more details and recommendations.

### 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](https://support.leap.energy/support/solutions/articles/73000586329-meter-status-guide) in our Knowledge Center.

Along with the `meter_id` and `meter_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`.

### 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.

### 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](https://support.leap.energy/support/solutions/articles/73000638613) guide.

---