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.
Create the Account used throughout the Storage-in-Switch workflow and confirm that the response includes account, address, utility, and tariff defaults.
Before you start, review the example project and paid add-on requirement in Forecasting Savings with Storage-in-Switch, and complete the Quick Start Guide to set up API access and authentication. This is Step 1; you will create the tutorial account here.
Account creation workflow
- Create or upsert an account with
PUT /rest/v1/accounts. - Include a stable and unique
providerAccountId. - Pass the customer’s address with ZIP code and country.
- Set
customerClass. - 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 Arcadia. Only your organization can access this account.
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/accountsUse 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:
| Field | Required | Description |
|---|---|---|
providerAccountId | Recommended | Your stable identifier for the account. Use this if you want to retrieve or update the account with /pid/{providerAccountId} endpoints. |
accountName | Recommended | Human-readable account name. |
address.addressString | Required for this example | Full customer address. Include ZIP code and country. |
properties.customerClass.dataValue | Recommended | Customer class used to filter and default tariffs. |
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 has up to 2 unique identifiers: accountId and providerAccountId.
accountIdis a universally unique identifier (UUID) that Arcadia generates when the account is created.providerAccountIdis an optional identifier supplied by your organization. It must be unique among your organization's accounts, but not across the entire API.
Use providerAccountId with PUT upserts to reuse identifiers from your existing system, such as a CRM, without storing the Arcadia-generated accountId. Do not supply an accountId when creating an account.
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.
| Value | Meaning |
|---|---|
| 1 | A residential customer. |
| 2 | A "general" customer. Use this to represent a commercial customer. |
| 4 | Special use. Typically used for agricultural tariffs, but some other specialized tariffs will fall into this category as well. |
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-exampleThe 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:
- Check the parsed
address, including latitude, longitude,zip, andcountry. The upcoming steps usezipandcountryto identify available utilities and tariffs. - Store the generated
accountIdfor subsequent calls if you are not usingproviderAccountId. - Review the defaulted utility and tariff. Accuracy values below
100indicate defaults or inferred values. In Step 2, confirm whether these values 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.
Updated about 22 hours ago
