Account

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, 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.

Address

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

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:

Properties can store a wide range of data for the account. This can include building attributes like buildingArea (square feet, etc.) and building type. It’s 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 Eligibilities

Government funded programs aimed at promoting Distributed Energy Resources are becoming more popular. These initiatives impact the financial viability of investing in solar and storage and are therefore an important part of a prospective buyer’s quote. Account Eligibilities help Switch users identify households who may qualify for different programs. eligibilityFlags is a read-only object that is auto populated when an account is created or updated. Most of these flags are tied to an Address; to ensure reliability, Account Eligibilities require the Account to have a complete Address (address1 should be populated at a minimum).

These eligibilities are based on various pieces of legislation, and the data is all pulled from publicly available sources.

Note that there are other eligibility categories that are defined in the 2022 Inflation Reduction Act that are not currently supported due to a lack of available data. These consist of the following:

• Brownfield sites as defined in 42 U.S.C. 9601(39)
• Energy communities that have 25% or greater tax revenue related to the extraction, processing, transport, or storage of coal, oil, or natural gas; AND Unemployment rate at or above national average rate of previous year
• Low income community Category 2: “Indian Land” as defined in the Energy Policy Act of 1992
• Low income community Category 3: Qualified Low-Income Residential Building Project
• Low income community Category 4: Qualified Low-Income Economic Benefit Project

Account Tariffs

You can specify the tariff rate plan for the account and 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:

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
{
	"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.

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:

Example

GET /rest/v1/accounts?search=Peets

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
	"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:

Example

These examples both return the same result.

GET /rest/v1/accounts/jke34kjlsd998er
GET /rest/v1/account?providerAccountId=abc123

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
	"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.

TIP - If you have a providerAccountId, you can perform an “upsert” using the Update an Account endpoint. It’s the same as the Add an Account endpoint but a PUT, not a POST (see below). 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 account’s likely utility and tariff:

Example 1 - minimum recommended values

POST /rest/v1/accounts

1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "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 postcode), 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 a likelihood field. Anything less than 100% means 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.

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
{
   "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 had 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
   "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).

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
{
   "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.

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 an 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 tariff or tariffs and can add or update properties. If a field is not present in the request, it’s 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

1
2
3
4
5
6
7
8
9
10
{
   "providerAccountId":"api-eg-008",
   "owner":"Mr Sun",
   "properties":{
      "customerClass":{
         "keyName":"customerClass",
         "dataValue":"1"
      }
   }
}

Here is the response back with the new owner set:

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
{
   "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 its 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.

Example 1 - Set properties collection values

The first example shows how 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:

1
2
3
4
{
    "keyName":"buildingArea",
    "dataValue":"2000"
}

The following would be returned:

1
2
3
4
5
6
7
8
9
10
11
12
{
   "status": "success",
   "count": 1,
   "type": "PropertyData",
   "results": [
      {
         "keyName": "buildingArea",
         "dataType": null,
         "dataValue": "2000"
      }
   ]
}

Example 2 - Set an account “header” field

The next example 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:

1
2
3
4
{
    "keyName":"type",
    "dataValue":"POTENTIAL"
}

The following would be returned.

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

1
2
3
4
5
{
    "keyName":"masterTariffId",
    "dataValue":"522",
    "accuracy":100
}

This will return back:

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

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
{
   "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}

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

1
2
3
4
5
6
{
   "status":"success",
   "count":0,
   "type":"PropertyData",
   "results":null
}