Re-engage Customers

For programs requiring customers to log into their utility account or enter utility account information on a form, it is expected to experience some level of customer drop off at this stage (i.e. customers who do not fully complete the process). In order to maximize conversions, it is critical to re-engage customers as quickly as possible after they abandon the meter authorization flow to remind them to complete the process. The value of this quick re-engagement and follow-up reminders over time is backed by extensive data in the ecommerce space and will increase the total number of meters in a partner’s grid services portfolio.

Leap’s Connect API enables you to automate this customer re-engagement by providing 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 allows Partners to monitor the status of their customer’s connections to individual utilities and the completion status of additional documents or forms requiring signature or agreement.

Re-engagement Strategy

The exact timing and messaging is up to you and your marketing team, but we’ve outlined Leap’s recommendations based on what we’ve seen work well:

1st touchpoint (the most important one):

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

2nd touchpoint:

  • Within 1 day of abandonment (time since last_interaction_date_time_utc)

3rd touchpoint:

  • Within 3 days of abandonment (time since last_interaction_date_time_utc)

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.


Connection Data & Reference IDs

Connection data will only be available if a Reference ID was included in the connection 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.

Track Customer Connections

The Connect API allows Partners to monitor the status of individual connections initiated by a customer (i.e. the customer clicked on the Connect URL). Every entry in the Connect API represents an individual Reference ID and the status of all requested utility connections and the completion status of any additional forms requiring signature or agreement for that Reference ID. The connection status codes and definitions are contained 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.

Automate Re-engagement Workflows

By periodically requesting the list of Reference IDs which have NOT_STARTED, PARTIAL, or ERROR connection status, Partners can create workflows to send automated requests to customers through email, mobile app or web portal to re-attempt or complete their connections in a timely manner. Leap has drafted a marketing toolkit which contains sample re-engagement messages that can be used based on the specific detailed status code provided in the API response.

The Leap Connect interface starts with any forms or questions that require an agreement or answer. Any required forms or questions must be completed in order for a Reference ID to reach a COMPLETED state. Once these are completed (if applicable), the user will be prompted to select their utility and authorize data sharing.

The Connect API allows Partners to assess which agreements or utility connections 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.

Processing the API Response

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