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 Arcadia 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	Description
accountId	String	This is the unique Arcadia ID of this `Account` object.
providerAccountId	String	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 Arcadia APIs. This must be unique within your accounts.
accountName	String	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 be 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 the 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 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 and will return an object with the properties below. Note that you can pass this in to add or update an account but you can also use add or update account properties to set these (and you are recommended to do so):

Name	Type	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	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	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. 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" properties like this.

Account properties are where you store these for your account and then the calculator will automatically take them into consideration. To get the properties to ask about 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 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:

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

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

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:

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/postcode 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

Example 1 - minimum recommended values

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 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, Arcadia 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 populatedAccount 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 had populated the individual address fields as well as the latitude and longitude of the address. We use Google's geocoding 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 info, 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.

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 an 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 Arcadia 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.

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 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:

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

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

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
}