Partner-Created Meters

For regions and programs that do not require customers to authorize utility data sharing, partners can directly create meters on the Leap platform using the Create Meters API described in this guide or by CSV upload in the Partner Portal.

The Create Meters endpoint supports the following use cases:

  • Create meters individually for desired program(s) as soon as customer agrees to participate within your enrollment workflow
  • Create meters in bulk for desired program(s)
  • Create meters in bulk and let Leap determine which meters may be eligible for which programs
  • Update previously created meters by overwriting with new data (see update_existing note at end of this guide)

Global Required Fields

The following fields are required to be included in the request body in order for a meter to be created. Failure to include one or more of these will result in a 400 error with the response body indicating which fields are missing.

Field NameDescription
partner_referenceUnique ID that partner uses to identify this device (e.g. serial number) or utility meter (e.g. customer or site ID). Check out the Utility Meters vs. Devices guide for guidance on how to define this.
transmission_regionChoose the ISO or geographic region this asset is part of
customer_classificationChoose residential vs. commercial
load_typesChoose one or more load types that are being controlled for demand response purposes
meter_typeChoose device vs. utility meter vs. submeter
street_1, postal_code, city, state_or_province_code, country_codeAddress where customer asset resides

Program Required Fields

Most programs require additional fields to be provided in order to meet eligibility requirements. If you know the program(s) that you want to enroll these meters into, you need to include these program-specific required fields as well.

It is also recommended to include optional fields since these additional parameters can help Leap quickly resolve issues or address questions from program operators without requiring additional data requests causing delays in the enrollment process.

Check out the following Knowledge Center articles for a list of required & optional fields:

🚧

Global vs. Program Required Fields

Only globally required fields are indicated as required in the API reference file. Additional program-specific required fields are not marked as required but still need to be added if you want the meter(s) to be enrolled in those programs.

Creating and Verifying New Meters

Use the following endpoints to create meters, check their status, save the new Leap meter IDs, and verify meter enrollment statuses:

STEP 1: Create Meters individually or in bulk by submitting asset data via JSON or CSV input. Store the resulting job_id.

📘

JSON input is detailed in the API reference file. For CSV input, use the Content-Type: text/csv header and include the CSV data as raw text in the POST body.

STEP 2: Use the Get Meters Job Status endpoint to confirm the status of each asset submitted for each job_id above.

If all globally required fields were included and the meter was created successfully, the resulting meter_id will be provided for each partner_reference ID within the assets array as shown in the example below.

{
  "job_id": "60c3c0bd-17b3-420b-b100-39a768bc5e39",
  "status": "COMPLETED",
  "created_at": "2025-06-04T17:31:04.268127Z",
  "updated_at": "2025-06-04T17:31:04.268132Z",
  "assets": [
    {
      "partner_reference": "CustomerAsset-123",
      "status": "COMPLETED",
      "status_detail": {
        "name": "METER_CREATED",
        "description": "A new meter was created."
      },
      "created_at": "2025-06-04T17:31:04.267226Z",
      "meter_id": "b19a52c4-beae-4542-ba3c-187639850a84"
    }
  ]
}

However, if a new meter was not created, the reason will be provided within the status and status_detail fields for each asset as shown in the example below.

{
  "job_id": "35678f05-f6c0-43c6-8c54-f43c81d44b5b",
  "status": "COMPLETED_WITH_ERRORS",
  "created_at": "2025-06-04T16:28:52.495723Z",
  "updated_at": "2025-06-04T16:28:52.495724Z",
  "assets": [
    {
      "partner_reference": "CustomerAsset-456",
      "status": "FAILED",
      "status_detail": {
        "name": "UNSUPPORTED_ZIP_CODE",
        "description": "The address is located in a unsupported zip code."
      },
      "created_at": "2025-06-04T16:28:52.495649Z"
    }
  ]
}

Job-level statuses:

  • PROCESSING - Job in process or in queue to be processed; check back later
  • FAILED - Internal error; reach out to Leap if request continues to fail
  • COMPLETED - Job processing completed successfully
  • COMPLETED_WITH_ERRORS - Job processing completed but there were one or more errors; check the asset-level status for more details

Asset-level statuses:

  • PROCESSING - Job in process or in queue to be processed; check back later
  • FAILED - Meter was not able to be created; check status_detail for reason
    • Applicable codes within status_detail.name:
      • ACCOUNT_MISMATCH, ADDRESS_INCOMPLETE,ADDRESS_NOT_FOUND, MULTIPLE_ACCOUNTS, UNSUPPORTED_ADDRESS, UNSUPPORTED_ZIP_CODE, VALIDATION_ERROR, PROCESSING_ERROR
    • Additional details provided in status_detail.description field
  • DUPLICATE - Meter was not able to be created due to a duplicate meter already in your portfolio; check status_detail for more details
    • Applicable codes within status_detail.name:
      • DUPLICATE_METER, DUPLICATE_REF_ID
    • Additional details provided in status_detail.description field
  • COMPLETED - Job processing completed successfully; meter was created or updated
    • Applicable codes within status_detail.name:
      • METER_CREATED, METER_UPDATED
  • MULTIPLE_PARTNER_REFERENCE - More than one Leap meter with that partner_reference exists in your account; ensure no duplicate partner_reference IDs exist if you are attempting to create a new meter and ensure only a single partner_reference exists if you are attempting to update the meter using the update_existing query parameter

📘

These statuses can also be seen on the Meter Uploads tab in the Portal. For more details on the statuses, check out the Meter Uploads Tab Statuses article in the Knowledge Center (portal credentials required).

🚧

Texas ESIID Requirement

In Texas, a valid electric service account or ESIID is required in order for a meter to be created. If a valid ESIID was not provided or was not able to be retrieved based on the address then the asset status would show as "FAILED" and the status_detail.name field would indicate the reason.


STEP 3: Optionally, call the Get Meter Enrollment endpoint for your new meter ID to track the meter enrollment status or poll the Search Meter Enrollments endpoint to track the statuses of all meters.

🚧

Missing Fields

These Meter Enrollment endpoints will provide the status of eligibility checks and indicate if any program-specific required fields were missing when the meter was created. If fields were missing, use the update_existing query parameter described below to add them.


❗️

Update meters withupdate_existing query parameter

Adding this optional query parameter, as shown on Create Meters reference file, allows for changing or adding fields to an already created meter. To avoid accidentally overwriting existing meter data, it should only be used and set to true when you explicitly want to overwrite all existing meter data fields for each applicable partner_reference. When this is set to true:

  • If an existing partner_reference is found, ALL fields will be updated with the new data uploaded
  • If no matching partner_reference is found, a new meter will be created
  • If multiple existing partner_reference are found, a MULTIPLE_PARTNER_REFERENCE error status will be provided and no meter will be created or updated.