Set Up an Account

Create a Switch Account, set the customer utility and tariff, and add account-level rates such as taxes.

When you want to do an analysis with the Arcadia API, first create an Account, then set a Tariff on that account. This page covers basic account setup. For a more detailed utility and tariff selection workflow, see Select the Right Utility and Tariff.

Create an account

An account is the basis for all analysis in the Arcadia API. It stores the data associated with a particular customer: their address, what tariff they're on, how much energy they're using, and more. Populate it with the data you need. In particular, specify where the customer is located and what kind of customer they are, such as residential or commercial.

Use the Account endpoint

Whether you're creating, modifying, or deleting an account, all operations happen through the Account endpoint:

https://api.genability.com/rest/v1/accounts

To create the account, send a PUT request to that URL:

PUT /rest/v1/accounts

Use the following JSON request body:

{  
    "providerAccountId":"example_account",  
    "accountName": "Example Account",  
    "address": {  
        "address1": "455 Market St",  
        "city" : "San Francisco",  
        "state" : "CA",  
        "zip" : "94105",  
        "country" : "US"  
    },  
    "properties": {  
        "customerClass": {  
            "keyName":"customerClass",  
            "dataValue":"1"  
        }  
    }  
}

The following sections explain the key parts of this request.

Why a PUT request?

There are two options for creating an account: you can send either a POST or a PUT request. A PUT request lets you use the providerAccountId property to set your own unique identifier.

`accountId` versus `providerAccountId`

Each account that you create in the Arcadia API can have two unique identifiers: accountId and providerAccountId. accountId is a UUID that is generated by the API for each account. providerAccountId is a unique identifier that you can generate to track the accounts you create within the API. If you have an existing database of accounts, you can use the identifiers you've already created rather than also storing the new IDs generated by the API.

A providerAccountId does not have to be unique within the API. Specifically, as long as you haven't already used the ID, it will be available for you to assign to an account.

Set an address

The most important property of an account is its address. This tells the API where your customer is located in the world, allowing it to use that data to do a lot of the account setup for you.

In the example, we're using structured address fields, but that's not the only way to do it. You can see all of the different options in the Address definition on the Account page. The most important thing to include is a zip code, either as part of addressString or in its separate zip field.

Set the customer class

The properties map is a dictionary that maps strings to account properties. In this request, we've set customerClass to 1, which tells the API that the customer is residential. Set this property when you create the account because you'll need it later when you specify the tariff.

Value	Meaning
1	A residential customer.
2	A "general" customer. Used to represent a commercial customer.
4	Special use. Not normally used.

Select a tariff

When an account is created, the Arcadia API will try to guess the best tariff for your customer based on the address and customerClass. For the account that we created above, the tariff will be automatically set to Pacific Gas & Electric's "E-1 Residential" tariff, since that is the most common tariff for residential customers in the 94105 ZIP code.

However, sometimes your customer is not on the most popular tariff, or a particular ZIP code has service from multiple utilities. In that case, there's still some work to do to set up the account. Make sure that an account has the correct tariff set on it because the tariff determines how much the customer pays to their utility for the energy that they use. That, in turn, determines the amount they could save by going solar.

To pick the correct tariff when the default doesn't work, we can use a data-driven approach with two steps:

Use the customer's address information to select the correct utility.
Based on that utility selection, pick the right tariff.

Choose the correct LSE

For many customers, there is only one utility, also called a load-serving entity (LSE) in the Arcadia API, that provides power in their area. Some customers, though, will have some choices. Use the Load Serving Entity endpoint to pick the right one.

The easiest way to see what utilities are available for your customer is to search by address or zip code. Continuing our example from before, you could use:

GET /rest/public/lses?zipCode=94105&country=US&residentialServiceTypes=ELECTRICITY

One important thing to note is the residentialServiceTypes=ELECTRICITY parameter on the end of the URL. This parameter makes sure that you only get back LSEs that serve electricity to residential customers. Otherwise, you would get back solar providers and other LSEs in the database. You could also use the commercialServiceTypes and industrialServiceTypes parameters for commercial and industrial customers, respectively.

Either query will return the following list:

{  
    "status": "success",  
    "count": 1,  
    "type": "LoadServingEntity",  
    "results": [  
    {  
        "lseId": 734,  
        "name": "Pacific Gas & Electric Co",  
        "code": "14328",  
        "websiteHome": "http://www.pge.com/"  
    }],  
    "pageCount": 25,  
    "pageStart": 0  
}

Since there's only one choice, you know that our customer is getting their electricity from PG&E. If there were more options, they would show up as additional entries in the results array. You can use the lseId field in the results to set the lseId property on the account:

PUT /rest/v1/accounts/pid/example_account/properties

{  
    "keyName":"lseId",  
    "dataValue":"734"  
}

Pick the right tariff

Now that you've created an account and chosen an LSE, you're ready to pick a tariff. For that, use the Account Tariff endpoint. This endpoint uses the data that you've already added to the account to show a list of available tariffs. For example, if you set up the account as a commercial account, the Account Tariff endpoint would only return commercial tariffs.

Use this request to see available tariffs:

GET /rest/v1/accounts/pid/example_account/tariffs

This will return a list of tariffs:

{  
    "status": "success",  
    "count": 21,  
    "type": "Tariff",  
    "results": [  
    {  
        "tariffId": 3215865,  
        "masterTariffId": 522,  
        "tariffCode": "E-1",  
        "tariffName": "Residential",
      
         /* more tariff data */
}]
}

You can see that, given the data we've provided so far, there are 21 tariffs to choose from. Arcadia helps you choose by ordering the tariffs returned from the Account Tariff endpoint by likelihood. The tariffs that are most likely to be correct for your customer are at the top, and the tariffs that are least likely are at the bottom.

Once you select the correct tariff from the list, you can set the masterTariffId property on the account just like we did for lseId earlier. Let's assume that our customer is on E-1:

POST /rest/v1/accounts/pid/example_account/properties

{  
    "keyName":"masterTariffId",  
    "dataValue":"522"  
}

`tariffId` versus `masterTariffId`

Why did we use masterTariffId to set our customer's tariff instead of tariffId? It's because tariff data changes periodically. E-1, for example, usually changes a few times per year. For each revision, we put a new tariff into the database with a unique tariffId. Logically, however, each of these new tariffs is a different version of a single "master" tariff. This family of tariffs is tied together with the masterTariffId property. Each version of the tariff will have a different tariffId, but they all have the same masterTariffId.

Add a tax rate to an account

The Arcadia database only has rates that appear in utility tariff books. That means that it does not have state, local, and other tax rates. To incorporate a tax, such as a Utility User's Tax (UUT), into a calculation on your account, you can include it in that account's tariffs:

PUT /rest/v1/accounts/{accountId}/tariffs
PUT /rest/v1/accounts/pid/{providerAccountId}/tariffs

{  
   "masterTariffId":"522",  
   "serviceType":"ELECTRICITY",  
   "rates":[  
      {  
         "chargeType":"TAX",  
         "rateName":"Utility Tax",  
         "rateBands":[  
            {  
               "rateAmount":0.085,  
               "rateUnit":"PERCENTAGE"  
            }  
         ]  
      }  
   ]  
}

Next steps

After you create the account, you can: