API Docs

Collect Data Authorizations

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

Sharemydata PGE

Note the video above shows the Legacy ShareMyData authorization journey

1. Introduction

Authorizations allow your customers to provide 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 make collecting authorizations from your customer easy and seamless, Leap provides two options. Each options allows you to generate a unique URL and to embed this URL into an email, web/mobile application, or any interface visited by your customers:

  1. Legacy ShareMyData Journey (CAISO Only)
  2. Leap Connect

2. Customer Journey

Once you have provided your customer the registration URL through your customer journey of choice, the customer will experience the authorization process as follows:

  1. The customer navigates to the Leap authorization flow through the registration link
  2. Leap redirects the customer to the authorization flow for the specified and/or selected utility for the customer to authorize data access
  3. (Leap Connect Only) Upon completion, the utility redirects the end-user back to Leap Connect indicating a successful authorization
  4. (Leap Connect Only - Optional): customers agrees to additional terms as required by the program
  5. Upon completion of the authorization proces the customer is redirected to the partner specified thank-you page

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

3. Generate Authorization URLs

Legacy ShareMyData Journey

The legacy ShareMyData flow allows you to provide customers a URL that directs them to a specific California utility's ShareMyData page to provide authoriation. These URLs are only available for California utilities specified below and do not allow for the signing of additional forms by the customer.

Base URL

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.

Leap Connect Flow

The Leap Connect is Leap's latest partner branded, multi-market authorization journey that allows customers to authorize multiple utilities and sign additional terms as required by customer type in one authorization session. Before being able to generate a functional authorization wrapper URL, your company must have its specific flow configured by Leap to include your branding, eSign forms and available utilities. To do so, please contact your Leap Partner Success representative.

https://onboarding.leap.energy/<org-name>/<url-friendly-title>/?requestedUtilities=<requested-utility>&refId=<refId>

Variables

AttributeDescription
org-nameLeap-generated name for your organization
url-friendly-titleThe name given to the specific Leap Connect flow that will appear in the URL. This can be set by your Partner Success Representative when creating the flow. This name is also available in the Partner Portal by navigating to the Meters tab, clicking "Add a Meter", selecting the desired flow, and creating a flow URL.
requestedUtilitiesAn optional parameter identifying the utilities which will be labelled as required for the commercial customers. Leaving this parameter blank will show all utilities in the region to customer. For residential customer, the requested utilties will have their logos appear in the flow with the other utilities configured for that flow by clicking the "Show All Utilities" option.
refIdAn option 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
NYISOConsolidated Edison (ConEd)cecony-utilityapi
NYISOOrange and Rockland Utilities (O&RU)oru-utilityapi
NYISOPSEG Long Island (PSEG-LI)psegli-utilityapi

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

Supported Regions & Customer Types

Region
CAISO
NYISO
Customer Types
Residential
Commercial

Need to test Leap Connect? Please contact your Partner Success Representative and a test journey will be configured for you.

Setup & Developer Notes

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 under 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. 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. An authorization URL without a Reference ID will not be traceable to a unique meter on the Leap platform.

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 a customer completed the authorization process (either on the utility website via the Legacy ShareMyData journey or within Leap Connect), 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 instead of Leap's generic page. When a customer is directed to the base URL provided to Leap, the URL will include the authorizationId and refId as parameters. 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>.

You can utilize the referenceId to match the returning authorization to your internal records. The authorizationId is informational only and can be used for troubleshooting. 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. To set your Confirmation Page, please email support@leap.ac or contact your Partner Success Representative.

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