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:

Listen for the utility credential webhook messages. You'll receive a webhook (if configured) that contains the verification_status for 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_status for 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 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
`id`	Arc'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 user `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 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
`utility_statements`	Plug
`utility_intervals`	Plug
`utility_remittance`	Bundle
`hosted_payments`	Bundle
`charge_cost`	Spark
`smart_charge`	Spark

For each of these features, Arc 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, Arc 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 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.