Developer Guides
Start typing to search…

Connect Reminders

For customers enrolling and authorizing their utility account through Leap Connect, it is expected that some customers will drop off (i.e. customers often drop off at the utility login screen). In order to maximize enrollments and grid services revenue, it is critical to re-engage customers who drop off as quickly as possible and remind them to complete the process. The value of this quick re-engagement and sequence of follow-up reminders is backed by extensive data in the ecommerce space and will increase the total number of meters in a partner’s grid services portfolio.

To make it easy to automate these customer reminders, Leap’s Connect webhooks or Connect API endpoint allows partners to receive real-time updates on how far the customer got in the process and when they dropped off. Along with the Connect tab in the Partner Portal, the Connect API/webhooks allow partners to monitor the status of their customer’s connections to individual utilities as well as the completion status of additional documents or forms requiring signature or agreement (if applicable).


Re-Engagement Strategy

The exact timing, messaging, and channels (email, mobile app push notification, and/or SMS) is up to you and your marketing team, but we’ve outlined Leap’s timing recommendations based on what we’ve seen work well:

1st touchpoint (the most important one):

  • Between 5 mins and 1 hour of abandonment
  • We recommend A/B testing different timing for optimal results

2nd touchpoint:

  • Within 1 day of abandonment

3rd touchpoint:

  • Within 3 days of abandonment

If your customers fail to complete their meter authorization after multiple follow–up touchpoints, we recommend putting them back into your standard marketing flow.

Additionally, Leap has drafted a marketing toolkit which contains sample re-engagement messages for you to tailor and customize for your own re-engagement campaign.


Leap Connect Status & Reference IDs

The Leap Connect interface starts with any forms or questions that require an agreement or answer. On the final step, the user will be prompted to select their utility and authorize data sharing. All required steps must be completed in order for a customer connection or session to reach a COMPLETED state.

The unique refId value per customer that is appended to the Leap Connect URL is used to track connection status. For completed connections, a Leap meter is eventually created (identified by it's own unique meter ID) and the refId value will be stored in the partner_reference field for easy correlation.

📘

Reference IDs & Connect Data

Connection and session data will only be available if a Reference ID was included in the Leap Connect URL and only after the customer has clicked on the URL. Getting data on links sent to customers that were not clicked on is not possibly through the Connect tab or API.


Recommended Method: Webhook Events

Leap provides detailed connect_session statuses across two different webhook events for advanced use cases, however it is possible to simplify the customer reminder logic as follows:

  • Subscribe only to the connect_session.updated event and look for the following status values:
    • "CREATED" – Add customer (based on partner_reference) to the reminder outreach schedule (e.g. send first reminder after 5m if you haven’t received a “COMPLETED” status before then)
    • "COMPLETED" – Mark this customer partner_reference as complete in your systems and remove customer from the reminder outreach schedule
🚧

Direct to Utility (CAISO) Flows

Direct to Utility (CAISO) flows do not use Leap Connect and therefore do not trigger the connect_session.updated event. They do, however, trigger the connect_session.authorization_updated event since they send users directly to their CA utility for authorization.

Webhook session vs. API connection statuses

  • Connect webhook – status tracked per individual Leap Connect session
    • A new session is created when a new Leap Connect tab/window is opened or when an idle session expires (24 hours)
  • Connect API – cumulative connection status is provided based on all Connect sessions to date

Alternative Method: Connect API Endpoint

The connection status codes used in the Connect API and Connections tab in the portal are outlined in the Connect Tab Status guide in the Leap Knowledge Center.

The Connect API has several request parameters that can allow Partners to request the connection data for individual Reference IDs or the data for all Reference IDs from specified connection start date or last interaction date (i.e. the last date which that Reference ID attempted a specific utility connection).

📘

Response Body Field Descriptions & Values

In the the Connect API reference file, you can click on the green 200 in the middle panel to see the response body field descriptions and possible values. Additionally, you can click on the green 200 in the right panel to see an example json response.

Example Connect API Response

{
  "id": "CAISO_62631455-9dfd-433b-9482-fd043f2336d4_Test1012",
  "transmission_region": "CAISO",
  "ref_id": "Test1012",
  "start_date_time_utc": "2023-01-11T02:44:57Z",
  "last_interaction_date_time_utc": "2023-01-11T02:45:50Z",
  "connection_status": "ERROR",
  "utility_connections": [
    {
      "authorization_uuid": "910bfb80-8b22-4341-8b5b-8752a21dccad",
      "utility_name": "SDG&E: San Diego Gas & Electric",
      "utility_is_required": true,
      "status": "ERROR",
      "error_code": "USER_CANCELED",
      "start_date_time_utc": "2023-01-11T02:44:57Z",
      "last_interaction_date_time_utc": "2023-01-11T02:45:50Z"
    }
  ],
  "agreements": {
    "prohibited_resource_attestation_status": "NOT_REQUIRED",
    "demand_response_participation_agreement_status": "NOT_REQUIRED",
    "generatorStatus": "NO_GENERATOR_ONSITE"
  }
}
🚧

Next Page Token Must be URL Encoded

When the response is large enough to span multiple pages or requests, ensure that the nextPageToken string in the response body is URL encoded before adding it to the page-token query parameter on the next request.

Processing the API Response

The Connect API allows Partners to assess which agreements or utility authorizations are outstanding for a Reference ID and tailor their re-engagement messaging accordingly. Once a connection is in a COMPLETED status, meters associated with that connection can take ~24 hours to appear on the Meters tab in the partner Portal or through the Meters API. At times this may be significantly longer due to delays in obtaining the meter data from the utility. Partners can monitor the meters associated with the connections by querying the Search Meters API endpoint and searching for meters added from the Last Interaction date in the Connect API associated with that Reference ID.

📘

Real-Time Updates to Connection Status

Connections status data is updated in real-time as customers click through the Leap Connect flow. If desired you can poll this endpoint once per minute without hitting any rate limits.


Step #1 - If connection_status is:

  • COMPLETED - Connection is successful and will typically show up as a meter on the Leap platform in ~24 hours. No customer follow-up is needed.
  • NOT_STARTED - Customer has clicked on Leap Connect URL but has not completed any steps. Resend the URL to the customer asking them to retry.
  • PARTIAL
    • Check the agreements object for any NOT_ANSWERED or DECLINED statuses and resend URL asking them to complete the agreement(s) and remainder of data sharing steps.
    • If there are no NOT_ANSWERED or DECLINED agreement statuses, check the status field within each utility in the utility_connections array for more details (proceed to Step #2 below)
  • ERROR - Check the error_code field within each utility in the utility_connections array for more details (proceed to Step #2 below)

📘

Status Code Definitions

For additional details on these top level connection, agreement, and utility connection statuses, check out the Connections Tab Status Codes knowledge center article.


Step #2 - If status within utility_connections is:

  • CONNECTED - Utility connection is successful. No additional customer action is needed for this utility.
  • NOT_CONNECTED - Customer has not completed the utility connection process. Resend the URL to the customer asking them to retry.
  • ERROR - Customer has logged into their utility or attempted to log into their utility but did not complete the process. Check the error_code field within each utility in the utility_connections array for more details. If appropriate, you can provide a tailored message to customer based on the error code to have them try again. See Connect Tab Status guide for details and recommended actions.
🚧

Multiple Utilities

For Commercial customers, multiple utilities may be required, so it is important to look at all objects within the utility_connections array to ensure that any connections marked as utility_is_required true have progressed to CONNECTED.

For Residential customers, there is generally only one utility but if a customer has intentionally or accidentally clicked on multiple utilities, there will be a separate object in the utility_connections array for each utility. Should the customer connect to a different utility than one which is included in the query parameter, the connection will remain in a PARTIAL status. You may choose not to follow-up with the customer in this case as they may not have a meter within the territory of the utility included in the query parameter.

Updated 13 days ago

What’s Next