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.
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
}
]
}