Account

Overview

An Account object is a place where you can store your customers' energy, cost, and savings data. Accounts typically represent your actual customers and potential customers, and are most useful when you map an account to a facility, such as a home or business. We recommend mapping an account to a site, and even if the site has multiple meters, although sometimes it's helpful to consider having an account for each individual utility meter location. Accounts are completely private and only visible to your organization. Your data is safe and secure with us.

This page gives a detailed description of the different properties and operations available for accounts. For a higher-level overview of creating and populating accounts, check out the how-to.

Data Definitions

The accountId is generated by Genability when the account is created. It is universally unique. If you have your own unique ID, you can put it (optionally) in the providerAccountId field. This is recommended as it means you can use your own IDs when calling all Account API endpoints and not have to save or synchronize ours.

Each account has a number of "header" fields that you can use to help you identify and group your accounts. These have names like accountName, customerOrgId and customerOrgName. There is also a field called properties that is a collection where specific properties can be stored. This includes customerClass ("RESIDENTIAL" vs "GENERAL"). Other examples include setting the cityLimits, buildingType, buildingVintage and so on. There are a large number of properties that can be set on an account (see below). An account also holds the tariff rate plan or plans, contracted supply rates, tax rates and more.

Account

The Account object has the following data structure.

Name Type Fields Description
accountId String M This is the unique Genability ID of this Account object.
providerAccountId String M If you use a unique identifier for this account in your own systems, you can specify that here. This allows you to quickly tie your own data with what you create with the Genability APIs. This must be unique within your accounts.
accountName String M This is the name of the account. We suggest using this field to identify the entity this account represents. For a small business, this could the name of the business. For a larger business with multiple locations, this could be the name of the location, e.g. Starbucks, Briarwood Mall.
customerOrgId String This allows grouping of accounts together. The customerOrgId should be an ID you use in your own systems to identify this account. Specifying a customerOrgId simplifies tying the account to your own data.
customerOrgName String This is the name of the account's organization. We suggest using this field to identify the name of the account's business. For example, Starbucks.
address Address Holds any address and geo-location data this account has.
timeZone String The timezone that this account is located in. They are in the tz database format.
owner String Use this to set the person who currently "owns" this account (otherwise its null)
status String This indicates the status of this account. Possible values are: ACTIVE (defaults to this), INACTIVE and DELETED.
type String This indicates the account type, whether of eg a customer or a prospect. Possible values are: CUSTOMER, POTENTIAL, TARGET and ARCHETYPE. By default, this is null.
properties Array of PropertyData This is a list of properties that exist on this account.
tariffs Array of Tariff This is a list of tariffs that are on the account.

Address

Each account has a field named address that will only show when populated, but when it is will return an object with the properties below. Note that you can pass this in to add or update account, but also use add or update account properties to set these (and you are recommended to do so):

Name Type Fields Description
addressString String Full free text string representing address. This is the property that is usually passed in. Zip will suffice but the full address is better.
addressName String A name associated with the address (e.g. Headquarters). Not usually set.
address1 String First part of the address. Usually populated by our address validation from the addressString passed in.
address2 String Second part of the address. Usually populated by our address validation from the addressString passed in.
city String City of the address. Usually populated by our address validation from the addressString passed in.
state String State of the address. Usually populated by our address validation from the addressString passed in.
zip String Postcode or ZIP code of the address. Usually populated by our address validation from the addressString passed in.
country String Usually the ISO Country Code of the address. Usually populated by our address validation from the addressString passed in.
formattedAddress String E This read-only field populated by our geo-coding and address parsing service (we use Google).
lon Double Longitude of the address. We'll populate this by geo-tagging the address.
lat Double Latitude of the address. We'll populate this by geo-tagging the address.

Account Properties

The Account has a field named properties which is a collection of zero or more properties. Each entry has a keyName (these correspond 1 to 1 with property values), and a dataValue. A PropertyData object has the following structure:

Name Type Fields Description
keyName String The unique name of this key, e.g. customerClass.
fromDateTime Date The optional starting date and time of this property, if applicable.
toDateTime Date The optional end date and time of this property, if applicable.
dataValue String The value of this account property.

Properties can store a wide range of data for the account. This can include building attributes like buildingArea (square feet etc) and building type. Its also common to use this array to save tariff specific options, electives or applicability arguments. Many tariff rate plans have rates on them that vary for certain attributes. For example, a Georgia Power Tariff will have a property for cityLimits because its rates differ on whether the customer is inside or outside of city limits. Rates in Chicago will usually vary depending on whether you live in an apartment or single family home, and whether your home is heated using gas or electricity. Commercial and Industrial tariffs almost always have one or more "rate applicability" property like this. Account properties is where you store these for your account, and then the calculator will automatically take them into consideration. To get the properties to ask about for a given tariff, call Get One Tariff with "populateProperties=true". Then send your answers to this endpoint.

Account Tariffs

You can specify the tariff rate plan for the account store it in its tariffs property (a collection). This is a rich structure that can hold multiple tariffs, contracted rate structures, and tax rates. Managing account tariff information is documented in this page.

Putting it all together - a JSON Example

Here's an example in JSON of a fairly common account with some properties populated:

{
    "accountId":"77f11344-62a9-4c2f-b8eb-e852e1c7f3ec",
    "providerAccountId":null,
    "accountName":"Starbucks, Briarwood Mall",
    "customerOrgId":"aje5kvkd7idwl2ksll",
    "customerOrgName":"Starbucks",
    "status":"ACTIVE",
    "properties":{
        "customerClass":{
           "keyName":"customerClass",
           "dataType":null,
           "fromDateTime":null,
           "toDateTime":null,
           "dataValue":"1"
        },
        "pdpProgramOption":{
           "keyName":"pdpProgramOption",
           "dataType":null,
           "fromDateTime":null,
           "toDateTime":null,
           "dataValue":"Alternating Days - Six Hour Window"
        },
        "phase":{
           "keyName":"phase",
           "dataType":null,
           "fromDateTime":null,
           "toDateTime":null,
           "dataValue":"Three"
        },
        "zipCode":{
           "keyName":"zipCode",
           "dataType":null,
           "fromDateTime":null,
           "toDateTime":null,
           "dataValue":"94115"
        }
    }
}

Note that accounts also have usage profiles that belong to them. Usage profiles are documented in this separate page.

Operations

Get a List of Accounts

Resource URI

GET /rest/v1/accounts

Request Parameters

Along with the standard pagination parameters, searching and sorting parameters, and the required security parameters, the following parameters are available as part of the request:

Name Type Description
searchOn String This is from the standard searching and sorting parameters. You can search within one or more of the attributes within the Account object. When search is specified but searchOn is not specified, the default fields searched on are accountName and customerOrgName. (Optional)

Example

GET /rest/v1/accounts?search=Peets
{
    "accountId":"jke34kjlsd998er",
    "providerAccountId":null,
    "accountName":"Peets Briarwood Mall",
    "customerOrgId":null,
    "customerOrgName":null,
    "status":null,
    "properties":{
        "customerClass":{
           "keyName":"customerClass",
           "dataType":null,
           "fromDateTime":null,
           "toDateTime":null,
           "dataValue":"GENERAL"
        }
    }
}

Get an Account

This allows you to retrieve a specific account based on either its Genability accountId or its providerAccountId, which is your own ID you may have assigned to this account.

Resource URI

The URIs are slightly different based on the ID you are using to retrieve the account. When using the accountId, put it as part of the URI. When using your own providerAccountID, it can also be part of the URI.

GET /rest/v1/accounts/{accountId}
GET /rest/v1/accounts/pid/{providerAccountId}

Request Parameters

The request parameters for retrieving an account are the required security parameters and the following, only used when searching by providerAccountId:

Name Type Description
providerAccountId String If you have set your own providerAccountId on the account, you can specify it here. This will only be used when there is no accountId specified as part of the URI. (Optional)

Example

These examples both return the same result.

GET /rest/v1/accounts/jke34kjlsd998er
GET /rest/v1/account?providerAccountId=abc123
{
    "accountId":"jke34kjlsd998er",
    "providerAccountId":null,
    "accountName":"Peets Briarwood Mall",
    "customerOrgId":null,
    "customerOrgName":null,
    "status":null,
    "properties":{
        "customerClass":{
           "keyName":"customerClass",
           "dataType":null,
           "fromDateTime":null,
           "toDateTime":null,
           "dataValue":"GENERAL"
        }
    }
}

Add an Account

This allows you to create a new account. You can add it with only a couple of fields set or flush it out more completely. Once added, all the fields can be updated at any time after the account has been created using the update methods documented below.

PRO-TIP! If you have a providerAccountId, you can perform an "upsert" using the Update an Account endpoint (it's the same as this but a PUT not a POST - see below) instead of the Add Account endpoint. If this will add an account if necessary, or update it if it already exists.

Resource URI

POST /rest/v1/accounts

Request Parameters

You pass in a valid account structure in the body of the request (see POST and PUT body for help with how to send the body of the request). This can be practically empty, or can include as many of the Account object's attributes as you know at the time it is added. The following fields, however, are recommended as these provide enough information to easily identify the account and allow us to be able to populate information such as the accounts likely utility and tariff:

Name Type Description
providerAccountId String Your unique ID for this account
accountName String Human readable name of the account
address.addressString or itemized fields String Full address is better, but ZIP/post code will suffice.
properties.customerClass 1=RESIDENTIAL, 2=GENERAL You can probably hard-wire this in your client code if you only have one type of customer
POST /rest/v1/accounts
{
   "providerAccountId":"api-eg-01",
   "accountName":"Example 1 API Home",
   "address":{
      "addressString":"221 Main Street, San Francisco, CA 94105"
   },
   "properties":{
      "customerClass":{
         "keyName":"customerClass",
         "dataValue":"1"
      }
   }
}

If the account has a location (more specifically, something that resolves to a valid ZIP or post code) it will usually have a default (the most likely) utility and tariff rate plan automatically set. We use address properties and other fields like customer class, usage levels and other relevant data to select the most likely rate plan. This is stored in the account's tariffs property. The entry also has has a likelihood field. Anything less than 100% and the tariff has been automatically set. 100% or null means that it was explicitly set. A source field will sometimes be set telling you where the value came from (was it defaulted or from an interview answer). Then, whenever an account is updated, Genability automatically reviews what was changed and determines whether changes should trigger the account’s default utility and tariff rate plan to be updated. Note that if the account has its tariff explicitly set, we don’t override it back to the best default. We only update defaulted values.

The response from adding an account contains the fully-populated Account object.

{
   "status":"success",
   "count":1,
   "type":"Account",
   "results":[
      {
         "accountId":"c2a630e8-c99a-4347-a460-d116e83439d2",
         "providerAccountId":"api-eg-10",
         "accountName":"Example 1 API Home",
         "customerOrgId":null,
         "customerOrgName":null,
         "address":{
            "addressString":"221 Main Street, San Francisco, CA 94105",
            "address1":"221 Main St",
            "city":"San Francisco County",
            "state":"CA",
            "zip":"94105",
            "country":"US",
            "lon":-122.3920575,
            "lat":37.7904127
         },
         "owner":null,
         "status":"ACTIVE",
         "type":null,
         "properties":{
            "customerClass":{
               "keyName":"customerClass",
               "dataType":"CHOICE",
               "dataValue":"1"
            }
         },
         "tariffs":[
            {
               "masterTariffId":522,
               "tariffCode":"E-1",
               "tariffName":"Residential",
               "lseId":734,
               "lseName":"Pacific Gas & Electric Co",
               "customerLikelihood":74.03,
               "endDate":null,
               "timeZone":"US/Pacific",
               "billingPeriod":"MONTHLY",
               "currency":"USD"
            }
         ],
         "projects":null
      }
   ]
}

Example 2 - individual address fields

In example 1 we passed in an address via the addressString property. Note that when the account was returned, we'd populated the individual address fields as well as the latitude and longitude of the address. We use Google's geo-coding service to do this. If you already have the address parsed out into its individual fields, then this approach is recommended as we won't override them based on the geo-coding results.

{
   "providerAccountId":"api-eg-11",
   "accountName":"Example 1 API Home",
   "address":{
      "address1":"221 Main Street",
      "city":"San Francisco", 
      "state":"CA",
      "zip":"94105",
      "country":"US"
   },
   "properties":{
      "customerClass":{
         "keyName":"customerClass",
         "dataValue":"1"
      }
   }
}

In the above call, we save the individual fields you passed in, rather than using the geo-service to parse them. We do still make a call to the geo-service to determine the latitude and longitude. To do this we concatenated all the fields together. Note that the addressString isn't populated on the response. If you want to see what Google sanitized the address into, you can call the Get Account endpoint with the optional request argument to populate the extended fields (fields=ext).

{
   "status":"success",
   "count":1,
   "type":"Account",
   "results":[
      {
         "accountId":"7918e7b9-9ae7-4942-bd77-b33ef0c8962a",
         "providerAccountId":"api-eg-01",
         "accountName":"Example 1 API Home",
         "customerOrgId":null,
         "customerOrgName":null,
         "address":{
            "addressString":null,
            "address1":"221 Main Street",
            "city":"San Francisco",
            "state":"CA",
            "zip":"94105",
            "country":"US",
            "lon":-122.3920575,
            "lat":37.7904127
         },
         "owner":null,
         "status":"ACTIVE",
         "type":null,
         "properties":{
            "customerClass":{
               "keyName":"customerClass",
               "dataType":"CHOICE",
               "dataValue":"1"
            }
         },
         "tariffs":[
            {
               "masterTariffId":522,
               "tariffCode":"E-1",
               "tariffName":"Residential",
               "lseId":734,
               "lseName":"Pacific Gas & Electric Co",
               "customerClass":null,
               "customerLikelihood":74.03,
               "endDate":null,
               "timeZone":"US/Pacific",
               "billingPeriod":"MONTHLY",
               "currency":"USD"
            }
         ],
         "projects":null
      }
   ]
}

Update an Account

This allows you to update an existing account. It also allows you to "upsert" an account if the providerAccountId is supplied but the account doesn't already exist.

PRO-TIP! This endpoint is great for doing a big update or an upsert, but we recommend you consider using the Update Account Property for field level property updates and Update Account Tariff for updating tariffs, supplier rates and tax rates, rather than using this endpoint.

Resource URI

PUT /rest/v1/accounts

Request Parameters

Just like Add Account, you pass in a valid JSON Account object in the request body. Include in this structure the accountId and/or providerAccountId plus any other attributes you want to be updated. Note that accountId and providerAccountId cannot be updated using this method. All the other top level fields of the account can be, though. The same options for passing in an addressString or individual address items that you have when creating an account are also available when updating one. You can also update the the tariff or tariffs and can add or update properties. If a field is not present in the request, its not removed from the database. In other words, each field passed in is added or updated but not deleted.

Example

Here's a example where we update the account (specifically the owner and customer class) that was added in the "Add" example, above:

PUT /rest/v1/accounts
{
   "providerAccountId":"api-eg-008",
   "owner":"Mr Sun",
   "properties":{
      "customerClass":{
         "keyName":"customerClass",
         "dataValue":"1"
      }
   }
}

Here is the response back with the new owner set:

{
   "status": "success",
   "count": 1,
   "type": "Account",
   "results": [
      {
         "accountId": "d2e46506-f641-45df-ab48-80d8c052b165",
         "providerAccountId": "api-eg-008",
         "accountName": "Example API Solar projection",
         "customerOrgId": null,
         "customerOrgName": null,
         "address": {
            "addressString": "221 Main Street, San Francisco, CA 94105, USA",
            "state": "CA",
            "zip": "94105",
            "country": "US",
            "lon": -122.39268,
            "lat": 37.790188
         },
         "owner": null,
         "status": "ACTIVE",
         "type": null,
         "properties": {
            "customerClass": {
               "keyName": "customerClass",
               "dataType": "CHOICE",
               "dataValue": "1"
            },
            "territoryId": {
               "keyName": "territoryId",
               "dataType": null,
               "dataValue": "3534"
            }
         },
         "tariffs": [
            {
               "masterTariffId": 522,
               "customerClass": null,
               "customerLikelihood": 74.03,
               "endDate": null,
               "timeZone": "US/Pacific",
               "billingPeriod": "MONTHLY",
               "currency": "USD"
            }
         ]
      }
   ]
}

Delete an Account

This allows you to delete a specific account, passing in the Genability accountId for the account. Note that the account still remains but it's status is switched to "DELETED".

Resource URI

DELETE /rest/v1/accounts/{accountId}

Request Parameters

The only request parameters for deleting an account are the required security parameters.

Example

DELETE /rest/v1/accounts/abc123

Add or Update an Account Property

This handy method allows you to set one field on the account. It's smart enough to add or update the field's value as it needs to. It also allows you to add or update practically any data field on the account including:

  • The top level or "header" fields such as accountName, owner or status
  • Any entry in the account.properties array
  • addressString and the other fields in the account.address sub-object
  • masterTariffIds in the account.tariffs array.

We have some examples below for all of these.

Resource URI

POST /rest/v1/accounts/{accountId}/properties
PUT /rest/v1/accounts/{accountId}/properties

POST /rest/v1/accounts/pid/{providerAccountId}/properties
PUT /rest/v1/accounts/pid/{providerAccountId}/properties

Request Parameters

The account property to add is specified within the body of the POST request. See the Account Property section above for more details on what the data structure for this is

Name Type Description
keyName String This is the keyName of the Property to add. (Required)
dataValue String This is the value of the Property being added. (Required)

Example 1 - Set properties collection values

The first examples shows how to to set a value in the properties collection on the account (i.e. the account.properties field). Here we are setting the building's area to 2,000 square feet. Call the following (POST or PUT would work):

PUT /rest/v1/accounts/pid/api-eg-008/properties

With this request body:

{
    "keyName":"buildingArea",
    "dataValue":"2000"
}

The following would be returned:

{
   "status": "success",
   "count": 1,
   "type": "PropertyData",
   "results": [
      {
         "keyName": "buildingArea",
         "dataType": null,
         "dataValue": "2000"
      }
   ]
}

Example 2 - Set an account "header" field

The next examples shows how to set one of the top level or "header" fields on the account. In this case we are setting the type field to "POTENTIAL", but you could do something similar for accountName, owner, customerOrgId and the other top level fields defined above. Call the following:

PUT /rest/v1/accounts/pid/api-eg-008/properties

With this request body:

{
    "keyName":"type",
    "dataValue":"POTENTIAL"
}

The following would be returned.

{
   "status": "success",
   "count": 1,
   "type": "PropertyData",
   "results": [
      {
         "keyName": "type",
         "dataType": null,
         "dataValue": "POTENTIAL"
      }
   ]
}

Example 3 - Set tariff data

For our final example we use this endpoint to set the electric tariff for the account.

PUT /rest/v1/accounts/pid/api-eg-008/properties

Note that in this case we've set the optional accuracy field. What this call is actually doing is confirming that the tariff that was defaulted is correct (100 means 100% accurate). Not passing in accuracy also means 100%. This call also supports passing in fromDateTime and/or toDateTime to add or update a tariff for a specific range. Note that this endpoint is only for electricity tariffs. Solar or other service types aren't supported here. Similarly, contracted rates or tax rates aren't supported either. To do those use the Add or Update Account Tariff endpoint.

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

This will return back:

{
   "status": "success",
   "count": 1,
   "type": "PropertyData",
   "results": [
      {
         "keyName": "masterTariffId",
         "dataType": null,
         "dataValue": "522",
         "accuracy": 100
      }
   ]
}

The result of all three of these calls is that buildingArea is in the properties collection, type is now set, and the tariff is confirmed. Making a call to the Get Account endpoint shows these are now set.

{
   "status": "success",
   "count": 1,
   "type": "Account",
   "results": [
      {
         "accountId": "4b1dd606-a72a-46b2-8c12-34db20be69fa",
         "providerAccountId": "api-eg-008",
         "accountName": "Example API Solar projection",
         "customerOrgId": null,
         "customerOrgName": null,
         "address": {
            "addressString": "221 Main Street, San Francisco, CA 94105, USA",
            "state": "CA",
            "zip": "94105",
            "country": "US",
            "lon": -122.39268,
            "lat": 37.790188
         },
         "owner": "Mr Sun",
         "status": "ACTIVE",
         "type": "POTENTIAL",
         "properties": {
            "buildingArea": {
               "keyName": "buildingArea",
               "dataType": null,
               "dataValue": "2000"
            },
            "customerClass": {
               "keyName": "customerClass",
               "dataType": "CHOICE",
               "dataValue": "1"
            },
            "territoryId": {
               "keyName": "territoryId",
               "dataType": null,
               "dataValue": "3534"
            }
         },
         "tariffs": [
            {
               "masterTariffId": 522,
               "customerClass": null,
               "customerLikelihood": 100,
               "endDate": null,
               "timeZone": "US/Pacific",
               "billingPeriod": "MONTHLY",
               "currency": "USD"
            }
         ]
      }
   ]
}

Delete an Account Property

This allows you to delete an existing property on the account.

Resource URI

DELETE /rest/v1/accounts/{accountId}/properties/{keyName}
DELETE /rest/v1/accounts/pid/{providerAccountId}/properties/{keyName}

Request Parameters

The account property to delete is specified as part of the URL. A "success" status is returned if the property is deleted or if the property does not exist.

Example

DELETE /rest/v1/accounts/123abc/properties/customerClass
{
   "status":"success",
   "count":0,
   "type":"PropertyData",
   "results":null
}