Direct to Utility (CAISO)

The Direct to Utility URL leverages the ShareMyData connection process in California and allows you to provide customers a URL that directs them to their specific utility's ShareMyData page to connect meters to Leap’s platform. These URLs are only available for the California utilities specified below and do not allow for the signing of additional forms by the customer.

It it recommended to use Leap Connect instead of this Direct to Utility URL as Leap Connect supports multiple markets as well as the ability for customers to sign additional agreements which are required in some scenarios. However, if the following conditions are met, it may be valuable to send customers directly to the California utility sites instead of starting with the Leap Connect utility selector screen:

• California users only
• Residential customers
• Customer utility known in advance

🚧

CA commercial customers are required to sign a Prohibited Resources Attestation form so the Leap Connect flow would be needed instead of this direct ShareMyData flow

URL Structure & Variables

Base URL

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

https://addleap.com/ElectricSpaceships/sce/getting-started?refId=123

Variables

Utility IDs

URL Query Parameters

Reference ID

It is highly recommended to use the refId query parameter noted above (with a unique value per customer) in order to:

1. Track connection status & re-engage customers with incomplete connections
2. Link Leap's records to your internal records

The value that is provided in this query parameter will be stored in the partner_reference field in the Meters API responses. You can then use this 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 a request back to your service. You should always ensure authentication and authorization of the user on your own platform. A Leap Connect URL without a unique Reference ID will not be traceable to a unique meter on the Leap platform.

The refId parameter has a 255-character limit and should follow standard URL character restrictions. Safe characters include digits (0-9), letters (A-Z, a-z), and a few special characters ("-", ".", "_", "*"). Any other special characters should be URL encoded before including in the refId parameter.

📘

Reference ID Updates

If needed, you can modify these partner_reference values, once a meter is authorized by the customer and on the Leap platform, via the partner portal or using the meter reference API endpoint.

Additional Custom Parameters

In order to include additional custom URL query parameters in the initial Leap Connect URL, these parameters need to be URL encoded and included in the additional_redirect_params parameter. These additional parameters, along with the refId parameter, will be saved with each user's session and upon successful completion of the authorization flow, Leap will restore all of these parameters on the final redirect URL back to your site or app.

As an example, to pass two additional parameters state=abcdef123 and test_parameter=value, the un-encoded value would be state=abcdef123&test_parameter=value. With URL encoding it becomes state%3Dabcdef123%26test_parameter%3Dvalue. The full URL to start the flow then becomes:

https://www.addleap.com/<org-name>/<utility-id>/getting-started?refId=<refId>&additional_redirect_params=state%3Dabcdef123%26test_parameter%3Dvalue

Passing these custom parameters allows for a variety of use cases including:

• Confirming which users completed the flow successfully
• Tracking state and user session information for customized responses and tracking
• Presenting different thank-you pages for different flows or campaigns

For example, each flow could have a custom query parameter added that indicates which marketing campaign, utility, geographic region, or partner program it is. Then upon successful authorization, the partner web server receiving the final redirect can look for that parameter and customize the response appropriately or decide to forward the user to a different URL or server instead.

Embedding URL within Mobile Apps

When embedding the Leap Connect or Direct ShareMyData URLs (with the variable RefID parameter) within a mobile app, use a webview for the user to complete the process since iframes are often blocked by the utilities. Additionally, it is recommended to use a custom User-Agent header as the default webview User-Agent could also be blocked by the utility web infrastructure.