Step 1 - Create Full Switch Account
Let's get going with the first of our five steps!
What's an Account?
To forecast savings using Switch with the Arcadia API, you first need to create an Account. An Account stores information about your customer's building (a.k.a. Site) in our database. This Account is only accessible to you. Account records can capture the site's utility and tariff rate plan, its class of customers, bills and meter data, tax rates, and more. Basically, anything that impacts the customer's energy costs and savings.
Add an Account
To create your account, send a PUT request to the Account endpoint:
PUT /rest/v1/accounts
Along with the following JSON request body:
{
"providerAccountId":"gdn-fst-eg-01",
"accountName":"GDN Forecasted Savings Tutorial Home",
"address":{
"addressString":"20480 Chapel Drive, Monte Rio 95462, US"
},
"properties":{
"customerClass":{
"keyName":"customerClass",
"dataValue":"1"
}
}
}
Let's break this request down and examine each piece individually.
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 will be added if it doesn't exist yet, or updated if it does. You use the providerAccountId
property as your own unique identifier. Why is that a good thing?
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.
- 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 the API. A
providerAccountId
does not have to be unique within the API, but must be unique among accounts you create.
By using a providerAccountId
and PUT upserts, you don't need to store our accountId
in your system.
Setting 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 you have validated and parsed an address into its component pieces in your app, we recommend you pass it through in its individual fields rather than as one string. You can see all of the different options for how to pass in the Address definition on the Account API Reference page. The most important thing to include is a ZIP code, either as part of the addressString
or in its separate zip
field. We also strongly recommend you pass in the country code as well.
Setting the Customer Class
The last thing to point out is the properties
map, which 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; you'll need it later when you're specifying your customer's tariff. 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. |
Getting 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. At any point after that, you can get a fresh copy using the Get Accounts endpoint, which is simply:
GET /rest/v1/accounts/pid/gdn-fst-eg-01
The response should look like this:
{
"status": "success",
"count": 1,
"type": "Account",
"results": \[
{
"accountId": "066c9738-5d46-4f62-ac25-f0c3c1e6fb9b",
"providerAccountId": "gdn-fst-eg-01",
"accountName": "GDN Forecasted Savings Tutorial 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 correctzip
andcountry
values, which we rely on in the upcoming steps. - The
accountId
has been generated and returned. If you are not using aproviderAccountId
(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. More on that in Step 2.
Summary
Congratulations! You have the first step behind you. You now have an Account with its customer class and address correctly set. You'll also notice that we defaulted its Utility (LSE) and its Tariff Rate Plan. In the next step, we'll explain the logic behind this defaulting, and you'll confirm or change these as necessary.
Updated 5 months ago