Users, credentials, accounts, and feature availability
Once one of your users has created a connection to their utility provider via Arc's Connect component, Arc will begin gathering their utility credential and account information. This guide outlines how to retrieve that information through a basic explanation of the Arc data model, as well as how to understand what Arc features are available for those accounts.
How it works
The Arc data model
The Arc data model is composed of the following elements:
- Users (
client_user_id) - A user is a person indexed by a
client_user_id, which is a unique identifier for one of your users. Arc requires that you provide a
client_user_idwhen first establishing a connection to your user's utility data via the Connect component.
- After the user represented by the
client_user_idcompletes Arc's Connect flow, any utility credentials and accounts that Arc discovers for this user will be related to their
- After the user represented by the
- Utility Credentials (
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.
utility_credential_idcan be used to initialize Arc'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).
- Utility Accounts (
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.
After a user inputs their utility provider credentials into Arc's Connect component, Arc 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 the
verification_statusfor each credential.
Here is a list of the potential values for
|The credentials were confirmed with the utility to be correct|
|The credentials were confirmed with the utility to be incorrect|
|The verification of the credentials are still being checked with the utility|
|There was an error with Arc verifying the credentials with the utility|
After your user's credentials are verified
After your user's credentials are verified, Arc will begin to search for valid accounts under the verified credentials. If found, Arc will search for historic statement and interval data (if available, see here for a list of utilities where Arc supports interval data).
Account discovery status
Arc 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 Arc gathers for each utility account (if that information is available):
|Field Name||Field Description|
|Arc's unique identifier for the given account|
|The user that the given account belongs to (provided by your application)|
|A reference to the credential that the given account belongs to|
|The name of the utility provider for the given account|
|The account holder's name|
|The utility provider's identifier for the given account|
|Address fields (multiple)||The service address of the account|
|The status of the account:|
|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|
|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.|
|What services the utility provides for the given account. Currently, only electric and gas are supported.|
|What Arc features are available for the given account (see 'Arc feature availability' section below)|
Historic statement and interval data
After Arc 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.
Arc 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, Arc provides the availability of features for the given account via a feature availability mapping.
The following features are included in Arc's feature availability mapping:
|Feature Name||Arc Product|
For each of these features, Arc will provide a status in the feature availability mapping:
|This feature is available|
|This feature will not be available for the foreseeable future (ie. the account cannot be parsed properly, Arc doesn't have coverage for the feature at the given utility, etc.)|
|We need to finish gathering data about this account before determining if this feature is available|
utility_account_updated webhook message will be triggered if any of the feature availability states change.
If an API request is made for feature that is in the
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, Arc will post a
utility_account_updated webhook message. Alternately you can use the List Utility Accounts or Get Utility Account request.
Updated 4 months ago