Automating Utility Data Collection with Plug

No more prodding prospects to manually collect utility statements for data entry into their solar proposal. You can now automate the collection of end-user utility account data to personalize your solar proposal using Arc's Plug feature.

Simply use Connect to generate a URL for your prospect to securely log into their electricity provider account. A webhook event fires when they've connected. At that point, you can call Switch's account API with the Arc ID to automatically create the account, and consumption profile using up to 12 months of the user's utility account statement data.

The end-to-end process is outlined here.

Initial Setup Requirements

In order to implement this workflow, you'll need to have the following setup in advance.

• An Arc tenant account and application with auth key and secret. Applications are initially setup in a sandbox environment and then made 'live' on request. You'll need to specify the environment Switch will use in the request.
• A Switch application for your organization in the legacy Arcadia product. Once you have an admin user with access to your organization in Switch, this may be created in a few clicks.
• During the beta period, The Arc Support team will need to made an admin update to link the Arc tenant to the Arcadia organization under which the applications have been created.

If you haven't developed applications yet, no worries, it's easy. To set up your secure integration with the Arc endpoints, see the guide here. For Arcadia setup, see this guide.

1. Get an Arc Access token to authenticate your requests

You can integrate this into your product, or do it manually from the developer portal when using your tenant's app credentials.

2. Create a Connect URL for a user's utility account at a prospect's Switch site

Creating a Connect URL is easy. It can be done through the developer portal, or by integrating your software with the Arc endpoints.

In that step, you'll specify the client user id for the site. This is the same ID you'll use to access the account in Arc after it's created upon making the first secure connection with the utility when the end user authenticates, and the same ID you'll send to create the account for the site's project analysis in Switch using the data from the connected utility account.

POST to https://api.arcadia.com/auth/connect_url

{  
  "client_user_id": "your_specified_userid"  
}

3. Confirm when the user's utility account is connected

In order to know when you have the utility account data to do your Switch savings analysis, you can either poll the Get User API for the client_user_id that you created when generating the connect URL or set up a Webhook to listen for new connected accounts. When you have a webhook set up, you'll receive the following event when they connect.

{ 
  "type": "utility_credential_verified",  
  "created_at": "2023-03-14T22:29:28.944-04:00",  
  "data": {  
    "id": 2384502,  
    "username": "[email protected]",  
    "sandboxed": true,  
    "created_at": "2023-03-14T22:29:23.829-04:00",  
    "updated_at": "2023-03-14T22:29:28.366-04:00",  
    "utility_name": "PG&E",  
    "client_user_id": "some_user_id",  
    "uses_test_scenario": false,  
    "verification_status": "verified",  
    "verification_updated_at": "2023-03-14T22:29:28.362-04:00",  
    "accounts_load_in_progress": true  
  }  
}

This is followed by a utility accounts detected event.

Then, confirming the historical readings are available will be an event like this.

{
  "type": "historical_utility_statements_discovered",
  "created_at": "2023-03-14T22:38:31.403-04:00",
  "data": {
    "client_user_id": "some_user_id",
    "utility_account_id": 2681510,
    "utility_statements": [
      {
        "id": 20075044,
        "kwh": 667,
        "tariff": null,
        ..

Now you're ready to run your Switch, where you can now automate account and/or default electricity profile creation with the user's data, simply by passing their ID to the Switch APIs.

4. Option A - Create a new Switch account and usage profile

Instead of collecting prospect information like address details manually, and setting it on the account via the use of Property Keys in the request, you can simply pass a single ID for a connected utility account holder.

POST /rest/v1/account

This Existing endpoint for creating new Switch Accounts now supports a new set of parameters: arcClientUserId, arcUtilityAccountId and arcEnvironment

Note: Any other existing parameters may still be included, such as customerClass, which is required to run a Savings Analysis ("dataValue":"1" for residential). Any data provided that would conflict with data acquired through the Arc integration will be preferred.

{
    "providerAccountId": "some_user_id",
    "accountName": "Some Account Name",
    "arcClientUserId": "some_user_id",
    "arcEnvironment": "sandboxed" // or "live"
    // other typical account creation fields here can be included
    "properties":{
      "customerClass":{
         "keyName":"customerClass",
         "dataValue":"1"}
      }
   }
}

This request will only succeed if exactly one valid Account/Profile is found in Arc. It will fail if another Switch Account has already been created that is affiliated with the Arc user/account.

When it succeeds, a Profile is automatically created using the 12 months of historical kWh consumption readings from the connected utility account.

PUT /rest/v1/account

This Existing endpoint for creating new Switch Accounts now supports a new set of parameters: arcClientUserId, arcUtilityAccountId and arcEnvironment

Note: As in the POST request, provided data is preferred.

{
    "providerAccountId": "some_user_id",
    "accountName": "Some Account Name",
    "arcClientUserId": "some_user_id",
    "arcEnvironment": "sandboxed"
  ... // other typical account update fields here can be included
}

If the Account is already linked to Arc, this request will update the Account with the latest from the Arc Utility Account, and create or update an Arc-linked Profile.

If the Account is NOT already linked to Arc, this request will establish the link (we'll store the arcClientUserId and the Arc Utility Account Id used) and update with data from Arc, and create an Arc-linked Profile from Utility Statement data -- unless the user has more than one valid Account/Profile worth of Arc data, in which case it will provide an error.

4. Option B - Add a usage profile to an existing Switch account

If you already have an Account or prefer not to alter that workflow, you can also retrieve the consumption data from the utility to add to an existing Switch Account via the Profiles endpoint.

POST /rest/v1/profiles

The existing endpoint for creating Switch Profiles will now support a new set of parameters: arcClientUserId, arcUtilityAccountId and arcEnvironment

As with Accounts, provided data is preferred.

{
    "providerAccountId": "some_user_id",
    "accountName": "Some Account Name",
    "arcClientUserId": "some_user_id",
    "arcEnvironment": "sandboxed"
  ... // other typical account update fields here can be included
}

PUT /rest/v1/profiles

The existing endpoint for updating Switch Profiles will now support a new set of parameters: arcClientUserId, arcUtilityAccountId and arcEnvironment

As with Accounts, provided data is preferred. The request body is identical in any of these scenarios.

{
    "providerAccountId": "some_user_id",
    "accountName": "Some Account Name",
    "arcClientUserId": "some_user_id",
    "arcEnvironment": "sandboxed"
  ... // other typical account update fields here can be included
}

5. Complete your Savings Analysis as before, using IB for the best results

You can find a complete tutorial on that workflow here.

Versioning

This version is available directly in legacy Arcadia APIs for a limited time. By 2024 it will only be available for new integrations through the Arc platform. Existing integrations on this initial version will continue to be supported.