API Docs

Collect Data Authorizations

Help your end customers authorize their sites for participation in a grid services program.

1. Introduction

Authorizations are instances of end users providing consent to participate in a grid services program, and share the requisite meter data.

Designing an effective authorization flow is critical to scaling a grid services program. Without an authorization, a customer cannot enroll or participate in a program.

To collect authorizations without any front-end development, Leap provides a Registration Link (URL). Embed this link into an email, web/mobile application, or any interface visited by your customers.

Sharemydata PGE

Working with a small set of customers? Paper/PDF authorization forms are also available.

https://www.addleap.com/<org-name>/<utility-id>/getting-started?refId=<refId>

Variables

AttributeDescription
org-nameLeap-generated name for your organization
utility-idstring identifying the utility providing data access
refId(Optional) string available to link authorized customers to your internal system

Utility IDs

RegionUtilityID
CAISOPacific Gas & Electric (PG&E)pge
CAISOSouthern California Edison (SCE)sce
CAISOSan Diego Gas & Electric (SDG&E)sdge

Utilities not listed in this table are not currently supported for automated authorizations by the Leap Platform.

Reference ID

You can utilize an internal Reference ID to link Leap's records to your internal records. Every meter record that is created on Leap's platform will contain the reference ID as provided in the registration link.

The reference-id has a 50-character limit and should follow standard URL character restrictions, which are a limited set of characters belonging to the US-ASCII character set. These characters include digits (0-9), letters (A-Z, a-z), and a few special characters ("-", ".", "_", "~").

Confirmation Page

After the customer clicks "Submit" on the utility website, they will be redirected to a Confirmation Page. The Confirmation Page as a default is set to Leap's generic Thank You Page, as shown above.

Partners also have the option to set their own Confirmation Page, to which Leap will redirect and include the authorizationId and refId as parameters. To set your Confirmation Page, please email support@leap.ac.

  • For example, if the Confirmation Page is set as https://partner.com/leap/thanks, Leap will redirect the customer to https://partner.com/leap/thanks?authorizationId=<authId>&refId=<refId>.

authorizationId an identifier to Leap's internal authorization record referenceId the refId as specified in the authorization link you've provided to the user

The authorizationId is currently informational only as it is the only record that can be shared at the time the authorization is completed. This could be used for troubleshooting but has not been needed for this purpose so far so this can easily be disregarded.

You can utilize the referenceId to match the returning authorization to your internal records. However, as this is a simple HTTP GET request, anyone could be making such request back to your service. You should always ensure authentication and authorization of the user on your own platform.

3. Embed the link and Share

Embed the registration link in a customer-facing interface. Email campaigns and in-app notifications are commonly used to engage end customers.

Before sending, be sure that:

  • Your org-name is specified correctly in the URL.
  • utility-id matches the service territory of each end customer.
  • You've setup a refId from your system to populate as a query parameter in the URL for each customer.

4. End-user authorization journey

Once the end-user navigates to the registration link that you provided by email, through an app or other means they can expect the following process:

  1. The end-user navigates to the Leap authorization flow through the registration link
  2. Leap redirects the end-user to the authorization flow from the specified utility
  3. Upon completion, the utility redirects the end-user back to Leap indicating a success
  4. Leap processes the successful authorization and redirects the end-user to the (partner specified) thank-you page

5. Sync Inventory with the Meter API

As customers complete their authorizations, new Meters become available in the Search Meters API. Set up a process to sync meter inventory to track conversion rates, collect metadata, and plan program enrollment.

If the reference-id attribute is included in your Registration Links, the reference-id will be exposed as the partner_reference field in the Search Meters API. You can then use the partner_reference to match meters in Leap's platform with customer accounts in your system.