Add an Account

To do a savings analysis with the Genability API, you first need to create an Account. An Account stores information about the building and its utility and tariff for a particular potential customer, for example:

  • Address (e.g. 221 Main St, San Francisco, CA 94105)
  • Customer Class (i.e. Residential for a home)
  • The Electricity Utility, Tariff and optionally any rate plan electives

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

PUT /rest/v1/accounts

Along with the following JSON request body:

{
    "providerAccountId":"example_account",
    "accountName": "Example Account",
    "address": {
        "addressString": "20480 Chapel Drive, Monte Rio 95462"
    },
    "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 you to use the providerAccountId property on the account in order to set 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 a UUID automatically generated by the API for each account.
  • providerAccountId is an additional, optional unique identifier you can use to keep track of accounts you create within the API. If you have an existing database of accounts, 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.

Setting an Address

The most important property of 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. 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 the addressString or in its separate zip field.

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 there are some other specialized tariffs that will fall into this category as well.

Getting the Account back

You now have an account representing a potential customer. Look up the account using the Accounts endpoint:

GET /rest/v1/accounts/pid/example_account

The response should look like this:

{
  "status": "success",
  "count": 1,
  "type": "Account",
  "results": [
    {
      "accountId": /* api-generated UUID */,
      "providerAccountId": "example_account",
      "accountName": "Example Account",
      ...
      "address": {
        "addressString": "20480 Chapel Drive, Monte Rio 95462",
        "address1": "20480 Chapel Dr",
        "city": "Monte Rio",
        "state": "CA",
        "zip": "95462",
        "country": "US",
        "formattedAddress": "20480 Chapel Dr, Monte Rio, CA 95462, USA",
        "lon": -123.011239,
        "lat": 38.469375
      },
      ...
      "properties": {
        "customerClass": {
          "keyName": "customerClass",
          ...
          "dataValue": "1"
        }
      }
   }]
}

In the next step, you’ll confirm your customer’s utility and electricity rate plan.


Next: Step 2 - Choose LSE & Tariff