HomeGuidesRecipesAPI ReferenceChangelog
Log In

Asynchronous Features

Collecting utility data depends on processing that happens asynchronously from API requests. We recommend using Webhooks to have the data delivered to you when it's all ready, rather than polling the Arc API.

When a user submits their utility credentials, Arc will automatically fetch all the data about the UtilityAccounts and UtilityStatements associated with utility credentials. That data will automatically be delivered to your webhook endpoints. Arc products outside of Plug, such as the Spark feature suite, do not currently have webhook integrations. These additional features may become available for a UtilityAccount as more data about that account is collected.

To make it easier to distinguish when different features are available to request, the UtilityAccount.feature_availability property maps platform features to their current availability state.

// An example UtilityAccount.feature_availability map
{
  // Determines which endpoints can be used with this account, based on the data we have been able to gather about it thus far
  "feature_availability": {
    "utility_statements": "NOT_AVAILABLE",
    "utility_intervals": "NOT_AVAILABLE",
    "charge_cost": "NOT_READY",
    "smart_charge": "NOT_READY",
    "hosted_payments": "NOT_AVAILABLE",
    "utility_remittance": "NOT_AVAILABLE"
  },
}

The current feature_availability features (keys) are:

  • utility_statements -- Fetching all billing statement data for an account
  • utility_intervals -- Fetching high-resolution (15 to 60 minute resolution) electricity usage data
  • charge_cost -- Calculating the cost of charging an EV at a particular time
  • smart_charge - Calculating the optimum EV charging schedule to minimize cost
  • hosted_payments - Allowing end users to pay their utility bill (with customizable charges and credits) through Arc instead of their utility
  • utility_remittance - Remitting to utilities for end users while allowing you to fully own their billing experience

As more features are added to Arc, they will automatically be presented as keys in this map.

  • The possible feature_availability states (values) are:
    • NOT_READY -- We need to finish gathering data about this account before determining if this feature is available
    • AVAILABLE -- This feature is ready to use
    • 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 some types of data, etc.) A UtilityAccountUpdated webhook will be triggered if any of the feature availability states change.

The general state flow is 'NOT_READY' → ( 'AVAILABLE' || 'UNAVAILABLE' ). If an API request is made for feature that is in the NOT_READY state or the NOT_AVAILABLE state, an HTTP 400 error will be returned.