Track Connection Status

Suggest Edits

In addition to the Connect tab in the Partner Portal, the Connect API allows Partners to monitor the status of their connections to individual utilities and the completion status of additional documents or forms requiring signature or agreement. Connections will appear in the Connect API for any Connect URLs that contain a Reference ID parameter. The Connect API provides Partners transparency into the state of customer connections and makes it easy for Partners to identify where they need to re-engage or take corrective actions at the connection level to increase the total number of successful connections and the number of resulting meters in a Partner’s grid services portfolio.

📘

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. Connection data on links sent to customers that were not accessed is not available.


Track Customer Connections

The Connect API allows Partners to monitor the status of all individual customer-to-utility 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"
           }
       }

🚧

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

All forms requiring an agreement of signature must also be completed in order for a Reference ID to reach a COMPLETED state. The Connect API allows Partners to assess which utility or agreements 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.

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
  • NOT_STARTED - Customer has clicked on Leap Connect URL but has not yet logged into their utility. Resend the URL to the customer asking them to retry.
  • PARTIAL - 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)

🚧

Data Refresh Rate & Stale Data

Connections status data is updated once per hour so in order to avoid reaching out to a customer based on stale data, it is recommended to poll the API no more than once/hour and to only take automated action on connection entries that have a top-level last_interaction_date_time_utc at least one hour in the past.


Step #2 - If status within utility_connections is:

  • CONNECTED - Utility connection is successful (proceed to Step #3 below)
  • 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. Provide a tailored message to customer based on the error code. 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.


Step #3 - If status within utility_connections is CONNECTED then check the agreements object:

  • Ignore any agreements parameters set to NOT_REQUIRED
  • For any other agreements parameters, check the status and follow-up with the customer to complete this final step. See Connect Tab Status guide for details and recommended actions.

🚧

Agreement Forms

These agreements will show as NOT_REQUIRED until the user selects their utility within the Leap Connect workflow

Updated 30 days ago

What’s Next