Accounts API

Use the Accounts API to create, retrieve, update, and delete accounts that store customer energy, cost, tariff, property, and savings data for a home, business, facility, or site.

Accounts typically represent customers or potential customers. We recommend mapping each account to a site, even when that site has multiple meters. In some cases, it can also be useful to create one account for each utility meter location.

Accounts are private to your organization. For the full account workflow, see Account APIs Overview. For a higher-level walkthrough of creating and populating accounts, see Create an account.

Data definitions

Arcadia generates a universally unique accountId when an account is created. If you maintain your own account identifier, store it in the optional providerAccountId field. Using providerAccountId lets you call account endpoints with your own IDs instead of saving and synchronizing Arcadia-generated IDs.

Each account has header fields that identify and group accounts, such as accountName, customerOrgId, and customerOrgName. The properties collection stores account-specific values, such as customerClass, cityLimits, buildingType, and buildingVintage. An account can also hold tariff rate plans, contracted supply rates, tax rates, and related data.

Account

The Account object has the following data structure.

Address

Each account has an address field that appears only when populated. You can pass address data when adding or updating an account, or you can use account property endpoints to set address fields.

Account properties

The Account object has a properties field, which is a collection of zero or more properties. Each entry has a keyName and a dataValue. A PropertyData object has the following structure:

Properties can store a wide range of account data, including building attributes such as buildingArea and building type. You can also use properties to save tariff-specific options, electives, or applicability arguments. Many tariff rate plans vary based on account attributes.

For example, a Georgia Power tariff can use cityLimits because rates differ based on whether the customer is inside or outside city limits. Rates in Chicago commonly vary based on whether a customer lives in an apartment or single-family home, and whether the home is heated with gas or electricity. Commercial and industrial tariffs often have one or more rate applicability properties like this.

Store these values as account properties so the calculator can take them into consideration. To retrieve the properties required for a tariff, call Get One Tariff with populateProperties=true, then send the answers to the account property endpoint.

Account Tariffs

Store tariff rate plans for an account in the tariffs collection. This structure can hold multiple tariffs, contracted rate structures, and tax rates. For details, see Account Tariffs API.

JSON example

This example shows a common account with populated properties:

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

Accounts can also have usage profiles. For details, see Profiles API.

Get Accounts

Resource URI

GET /rest/v1/accounts

Request parameters

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 One Account

Retrieve a specific account by Arcadia accountId or by your providerAccountId.

Resource URI

The URI depends on the ID you use to retrieve the account. Use the accountId path for Arcadia IDs and the pid path for your own providerAccountId values.

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/accounts/pid/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 Account

Create a new account with only a few fields, or include more complete account details in the initial request. After the account is created, you can update its fields with the update methods documented below.

lightbulb

If you have a providerAccountId, you can perform an upsert with the Update Account endpoint. The update endpoint uses PUT instead of POST and creates the account if needed or updates it if it already exists.

Resource URI

POST /rest/v1/accounts

Request parameters

Pass a valid account structure in the request body. The body can be minimal or can include as many Account attributes as you know when the account is created.

These fields are recommended because they help identify the account and allow Arcadia to populate information such as the account's likely utility and tariff:

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 that resolves to a valid ZIP or postcode, Arcadia usually sets the most likely utility and tariff rate plan automatically. Arcadia uses address properties, customer class, usage levels, and other relevant data to select the most likely rate plan. This selection is stored in the account's tariffs property.

The tariff entry can include a likelihood field. A value below 100% means the tariff was automatically set. A value of 100% or null means the tariff was explicitly set. A source field may also indicate where the value came from, such as a default or an interview answer.

When an account is updated, Arcadia reviews the changes and determines whether they should update the account's default utility and tariff rate plan. If the account tariff was explicitly set, Arcadia does not override it with the best default. Only defaulted values are updated.

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, the request passed an address with the addressString property. When the account was returned, Arcadia populated the individual address fields and the address latitude and longitude using Google's geocoding service. If you already have the address parsed into individual fields, use those fields so Arcadia does not override them based on geocoding 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 this request, Arcadia saves the individual fields you passed instead of using the geocoding service to parse them. Arcadia still calls the geocoding service to determine latitude and longitude by concatenating the fields. The addressString field is not populated in the response. To see the sanitized address, call Get One Account with accountId with 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 Account

Update an existing account, or upsert an account when providerAccountId is supplied and the account does not already exist.

lightbulb

Use this endpoint for large updates or upserts. For field-level property updates, use Add or Update an Account Property. For tariffs, supplier rates, and tax rates, use Add or Update Account Tariff.

Resource URI

PUT /rest/v1/accounts

Request parameters

Pass a valid JSON Account object in the request body. Include accountId and/or providerAccountId, plus any other attributes you want to update. You cannot update accountId or providerAccountId with this method. All other top-level account fields can be updated. You can pass addressString or individual address fields, and you can also update tariffs and properties. If a field is not present in the request, it is not removed from the database. Each field passed in is added or updated, not deleted.

Example

This example updates the account owner and customer class from the Add Account example:

PUT /rest/v1/accounts

{
  "providerAccountId":"api-eg-008",
   "owner":"Mr Sun",
   "properties":{
      "customerClass":{
         "keyName":"customerClass",
         "dataValue":"1"
      }
   }
}

The response returns the updated account:

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

Delete a specific account by passing the Arcadia accountId. The account record remains, but its status changes to DELETED.

Resource URI

DELETE /rest/v1/accounts/{accountId}

Request parameters

Only authentication is required.

Example

DELETE /rest/v1/accounts/abc123

Add or Update Account Property

Set one field on an account. This endpoint adds the field if it does not exist or updates the field if it already exists. You can add or update many account fields, 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

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

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

Request parameters

Specify the account property in the request body. See Account Properties for the data structure.

Example 1: Set properties collection values

The first example sets a value in the account.properties collection. This request sets the building area to 2,000 square feet.

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

With this request body:

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

The response returns the updated property:

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

Example 2: Set an account header field

The next example sets one of the top-level account header fields. This request sets type to POTENTIAL, but you can use the same pattern for accountName, owner, customerOrgId, and other top-level fields.

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

With this request body:

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

The response returns the updated field.

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

Example 3: Set tariff data

This example uses the 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
}

The response returns the updated tariff property:

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

After these calls, buildingArea is in the properties collection, type is set, and the tariff is confirmed. Call Get Account to verify the updated values.

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

Delete an existing property on an account.

Resource URI

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

Request Parameters

Specify the account property to delete in the URL. The endpoint returns "success" 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
}

Next steps

1. Return to Account APIs Overview to choose another account workflow.
2. Use Account Properties API to store account-specific values used by tariff applicability and calculations.
3. Use Account Tariffs API to assign tariff rate plans, contracted rates, or historical tariff changes.
4. Use Account Rates API to inspect the rates associated with an account's assigned tariffs.