HomeGuidesAPI Reference
Log In

Arc basics

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_id when first establishing a connection to your user's utility data via the Connect component.
    • After the user represented by the client_user_id completes Arc's Connect flow, any utility credentials and accounts that Arc discovers for this user will be related to their client_user_id.
  • 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.
    • The utility_credential_id can 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.


Credential authentication

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:

Here is a list of the potential values for verification_status:

verifiedThe credentials were confirmed with the utility to be correct
rejectedThe credentials were confirmed with the utility to be incorrect
pendingThe verification of the credentials are still being checked with the utility
errorThere 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 NameField Description
idArc's unique identifier for the given account
client_user_idThe user that the given account belongs to (provided by your application)
utility_credential_idA reference to the credential that the given account belongs to
utility_nameThe name of the utility provider for the given account
service_customer_nameThe account holder's name
account_numberThe utility provider's identifier for the given account
Address fields (multiple)The service address of the account
statusThe 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 user

Locked: The account has been locked by the utility

Unknown: There was an issue getting account data
most_recent_tariffInformation 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
flagsImportant 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.
servicesWhat services the utility provides for the given account. Currently, only electric and gas are supported.
feature_availabilityWhat 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 NameArc Product

For each of these features, Arc will provide a status in the feature availability mapping:

AVAILABLEThis feature is available
NOT_AVAILABLEThis 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.)
NOT_READYWe 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_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, Arc will post a utility_account_updated webhook message. Alternately you can use the List Utility Accounts or Get Utility Account request.