Step 1 - Create an Account

Let’s get going with the first of our five steps!

What’s an Account?

To forecast savings using Switch with the Genability 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 customer, 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "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 Genability 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 actually 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 though 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.

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
    "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 set 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. 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.

Next: Step 2 - Choose LSE & Tariff