Once one of your customers has created a connection to their utility provider via Arcadia Platform’s Connect component, that will begin gathering their utility credential and account information. This guide outlines how to retrieve that information through a basic explanation of the Arcadia Platform data model, as well as how to understand what the Arcadia Platform features are available for those accounts.
How it works
The Arcadia data model
The Arcadia data model is composed of the following elements:
-
Users (indexed by
client_user_id) - A user is a person indexed by aclient_user_id, which is a unique identifier for one of your customers. Arcadia Platform requires that you provide aclient_user_idwhen first establishing a connection to your customer’s utility data via the Connect component.- After the user represented by the
client_user_idcompletes Arcadia Platform's Connect flow, any utility credentials and accounts that Arcadia Platform discovers for this user will be related to theirclient_user_id.
- After the user represented by the
-
Utility Credentials (indexed by
utility_credential_id) - A credential represents a unique connection between a user and a utility. A user might have multiple credentials if they have open accounts at more than one utility provider, or multiple credentials at a single utility.- The
utility_credential_idcan be used to initialize Arcadia Platform's Connect component in ‘update mode’ if you need to repair the connection to a user’s utility (typically caused by a password change by the user).
- The
-
Utility Accounts (indexed by
utility_account_id) - This represents an account that a user has with a utility provider. A user may have multiple active accounts at any number of utility providers.
Credential authentication
After a user inputs their utility provider credentials into Arcadia Platform's Connect component, Arcadia Platform will attempt to verify those credentials with the utility. To obtain the results of the verification you can:
-
Listen for the utility credential webhook messages. You’ll receive a webhook (if configured) that contains the
verification_statusfor the credential. Here’s an example of the webhook you’ll receive when the verification is successful. -
Poll the Credentials API. You can use the List Utility Credentials operation filtered by the user’s
client_user_id. This call will return a list of credentials for the given user, including theverification_statusfor each credential.
Here is a list of the potential values for verification_status:
| Status | Description |
|---|---|
| verified | The credentials were confirmed with the utility to be correct |
| rejected | The credentials were confirmed with the utility to be incorrect |
| pending | The verification of the credentials are still being checked with the utility |
| error | There was an error with Arcadia Platform verifying the credentials with the utility |
After your user’s credentials are verified
After your user’s credentials are verified, Arcadia Platform will begin to search for valid accounts under the verified credentials. If found, Arcadia Platform will search for historic statement and interval data (if available, see here for a list of utilities where Arcadia Platform supports interval data).
Account discovery status
Arcadia Platform will start gathering basic account information with the given utility provider for verified credentials. If at least one account is discovered (and you have registered webhook listeners) you will receive the utility_accounts_discovered webhook message. You can also poll the List Utility Accounts or Get Utility Account endpoints to see discovered accounts.
Basic Account Data
Here is a list of fields that Arcadia Platform gathers for each utility account (if that information is available):
| Field Name | Field Description |
|---|---|
| id | Arcadia Platform’s unique identifier for the given account |
| client_user_id | The user that the given account belongs to (provided by your application) |
| utility_credential_id | A reference to the credential that the given account belongs to |
| utility_name | The name of the utility provider for the given account |
| service_customer_name | The account holder’s name |
| account_number | The utility provider’s identifier for the given account |
| Address fields (multiple) | The service address of the account |
| status |
The status of the account: Active: The account is active with the utility Closed: The account is closed with the utility Incomplete: The account has not been fully set up by the customer Locked: The account has been locked by the utility Unknown: There was an issue getting account data |
| most_recent_tariff | Information about the tariff currently applied to the account: code, name, utility provider name, and the date when the tariff was first applied to the account |
| flags | Important account statuses. Currently, the only status that will appear here is “Utility statement past due” if there is at least 1 utility statement on the account that is past due. |
| services | What services the utility provides for the given account. Currently, only electric and gas are supported. |
| feature_availability | What Arcadia Platform features are available for the given account (see ‘Arcadia Platform feature availability’ section below) |
Historic statement and interval data
After Arcadia Platform discovers accounts, it begins to gather historic statement and (if supported at the given utility) interval data for the account. See the Plug product guide for a breakdown of how to be notified when historic statement and interval data is available.
Arcadia Platform feature availability
Certain features, such as Bundle’s payment flows or Spark’s charge cost and smart charge calculation capabilities, are not available for all utility accounts. For every account, Arcadia Platform provides the availability of features for the given account via a feature availability mapping.
The following features are included in Arcadia Platform’s feature availability mapping:
| Feature Name | Arcadia Platform Product |
|---|---|
| utility_statements | Plug |
| utility_intervals | Plug |
| utility_remittance | Bundle |
| hosted_payments | Bundle |
| charge_cost | Spark |
| smart_charge | Spark |
For each of these features, Arcadia Platform will provide a status in the feature availability mapping:
| Status | Description |
|---|---|
| AVAILABLE | This feature is AVAILABLE |
| NOT_AVAILABLE | This feature will not be available for the foreseeable future (ie. the account cannot be parsed properly, Arcadia Platform doesn't have coverage for the feature at the given utility, etc.) |
| NOT_READY | We need to finish gathering data about this account before determining if this feature is AVAILABLE |
A UtilityAccountUpdated webhook will be triggered if any of the feature availability states change.
If an API request is made for feature that is in the NOT_READY or NOT_AVAILABLE state, an HTTP 400 error will be returned.
Keeping up to date on account and feature availability changes
When there is any update to account data, Arcadia Platform will post a utility_account_updated webhook message. Alternately you can use the getUtilityAccounts or getUtilityAccount request.