Step 1: Create a Storage-in-Switch Account

Create the Account used throughout the Storage-in-Switch workflow and confirm that the response includes account, address, utility, and tariff defaults.

Account creation workflow

1. Create or upsert an account with PUT /rest/v1/accounts.
2. Include a stable and unique providerAccountId.
3. Pass the customer’s address with ZIP code and country.
4. Set customerClass.
5. Confirm the response includes the parsed address, defaulted utility, and defaulted tariff.

What's an account?

To forecast savings using Switch with the Arcadia API, first create an Account. An account stores information about your customer's building, also called a site, in our database. This account is only accessible to your organization.

Account records can capture anything that impacts the customer's energy costs and savings, including the site's utility, tariff rate plan, customer class, bills, meter data, and supplemental tax rates.

Add an account

To create your account, send a PUT request to the Account endpoint:

PUT /rest/v1/accounts

Use the following JSON request body:

{  
   "providerAccountId":"storage-switch-example",  
   "accountName":"Storage-in-Switch Example Home",  
   "address":{  
      "addressString":"20480 Chapel Drive, Monte Rio 95462, US"  
   },  
   "properties":{  
      "customerClass":{  
         "keyName":"customerClass",  
         "dataValue":"1"  
      }  
   }  
}

The following table explains the key fields in the request:

Why a PUT request?

You can send either a POST or a PUT request to create an account. Using a PUT request allows an "upsert", where the account is added if it doesn't exist yet or updated if it does. You use the providerAccountId property as your own unique identifier.

accountId versus providerAccountId

Each account you create in the Arcadia API has up to two unique identifiers: accountId and providerAccountId.

• accountId is our automatically generated UUID, created at the time the account is added. Don't pass one in. We generate it automatically.
• providerAccountId is an additional, alternative, optional unique identifier you can use to keep track of accounts you create within the API. In other words, this is your unique ID. If you have an existing database of accounts, such as your CRM's potential or account ID, you can use the identifiers you've already created instead of storing the new IDs generated by Arcadia. A providerAccountId does not have to be unique within the API, but must be unique among accounts you create in your organization.

By using a providerAccountId and PUT upserts, you don't need to store our accountId in your system.

When you use providerAccountId, you can retrieve and update the account through the /pid/{providerAccountId} path for supported endpoints.

Set an address

The most important data on an account is its address. This tells the API where your customer is located in the world and allows the API to do a lot of account setup for you.

The above example uses the addressString property of the address, but that's not the only way to do it. If your application already validates and parses addresses, pass the parsed address fields instead of a single string. You can see all of the different options for how to pass in the Address definition on the Account API Reference page. Include a ZIP code and country, either as part of addressString or in separate fields such as zip and country.

Set the customer class

The properties map is a dictionary that maps strings to account properties. In this request, you set customerClass to a value of 1. This value tells the API that your customer is a residential customer. It's important to set this property when creating your account because you'll need it when specifying your customer's tariff in a later step. You can see the other options for the customerClass property in the table below.

Get the account back

When you make the call to create the account, the API returns a fully populated copy of it like the one below. After that, you can get a fresh copy using the Get Accounts endpoint:

GET /rest/v1/accounts/{accountId}
GET /rest/v1/accounts/pid/{providerAccountId}

Example

GET /rest/v1/accounts/pid/storage-switch-example

The response includes the account, parsed address, defaulted utility properties, and defaulted tariff used in the next step:

{  
    "status": "success",  
    "count": 1,  
    "type": "Account",  
    "results": [  
        {  
            "accountId": "066c9738-5d46-4f62-ac25-f0c3c1e6fb9b",  
            "providerAccountId": "storage-switch-example",  
            "accountName": "Storage-in-Switch Example Home",  
            "customerOrgId": null,  
            "customerOrgName": null,  
            "address": {  
                "addressString": "20480 Chapel Drive, Monte Rio 95462, US",  
                "address1": "20480 Chapel Dr",  
                "city": "Monte Rio",  
                "state": "CA",  
                "zip": "95462",  
                "country": "US",  
                "lon": -123.011239,  
                "lat": 38.469375  
            },  
            "status": "ACTIVE",  
            "type": null,  
            "accountManager": null,  
            "assignee": null,  
            "contacts": null,  
            "properties": {  
                "customerClass": {  
                    "keyName": "customerClass",  
                    "dataType": "CHOICE",  
                    "dataValue": "1"  
                },  
                "lseId": {  
                    "keyName": "lseId",  
                    "displayName": "Pacific Gas & Electric Co",  
                    "dataType": "INTEGER",  
                    "dataValue": "734",  
                    "accuracy": 55.31  
                },  
                "territoryId": {  
                    "keyName": "territoryId",  
                    "dataType": "INTEGER",  
                    "dataValue": "3541",  
                    "accuracy": 100  
                }  
            },  
            "tariffs": [  
                {  
                    "masterTariffId": 522,  
                    "tariffCode": "E-1",  
                    "tariffName": "Residential",  
                    "lseId": 734,  
                    "lseName": "Pacific Gas & Electric Co",  
                    "customerClass": null,  
                    "customerLikelihood": 55.31,  
                    "endDate": null,  
                    "timeZone": "US/Pacific",  
                    "billingPeriod": "MONTHLY",  
                    "currency": "USD"  
                }  
            ],  
            "projects": null  
        }  
    ]  
}  

A few things to note:

• The address has been parsed into its component pieces, including latitude and longitude. Most importantly, this sets the correct zip and country values, which we rely on in the upcoming steps.
• The accountId has been generated and returned. If you are not using a providerAccountId (we recommend you do), then store this in your database for subsequent calls.
• We have defaulted this account's most likely utility and tariff rate plan. Accuracy values below 100 indicate defaults or inferred values. In Step 2, you'll confirm whether the defaulted utility and tariff match the customer’s bill.

Summary

You now have an account with its customer class and address set. The response also shows the defaulted utility (LSE) and tariff rate plan. In the next step, you'll review the defaulting logic and confirm or change these values as needed.