HomeGuidesAPI ReferenceChangelog
Log In
Guides

Key Differences

Suggest Edits

Introduction

If you are currently using Legacy Plug APIs (2021-11-17 and 2022-10-13), this guide will help you prepare for upgrading to the 2024-02-21 version of the Plug API.

The 2024-02-21 version of the Plug API is a significant change from the previous versions (2021-11-17 and 2022-10-13), which are now considered the 'Legacy Plug' API. To clearly indicate which API versions we are talking about in this document, we'll use the version names.

Differences

Data is not carried over into the new Plug API

The current Plug API uses an entirely different backend and databases compared to the Legacy Plug API. This means, you will have a clean slate.

🚧

Do NOT expect any ID or URL uses in legacy versions to work in the current Plug API. The structure of all responses has changed.

The API will continue to run on the api.arcadia.com domain and will continue to require the Arc-Version header to determine how to handle requests.

To assist with the transition, we can help you re-submit all of your Credentials you've used with our legacy APIs to the current Plug API. If you're interested in this, please reach out to your Customer Success Manager, Account Manager, or the our Support team.

New Data Model

The Arcadia data model is documented detailed here. Some notable differences are:

  • There is no concept of a User anymore. Instead, Credentials and Files are the top level resources created by customers. Both of these can be deleted on request, and similar to Legacy Plug, this will delete their derived resources like Accounts, Meters and Statements.
  • Utility Accounts are now Accounts.
  • Utility Statements are now Statements.
  • Significantly more Statement and Meter level data is available in the 2024-02-21 version . There are now detailed Statement endpoints which include line items on Charges and Usages.
  • Tariff names are included in detailed Statement responses, but the 2024-02-21 version does not yet include Genability main_tariff_id.
  • Meters and Accounts can belong to multiple Credentials.
  • Meters can belong to multiple Accounts.

New Dashboard

The Arcadia Dashboard has moved to https://dashboard.arcadia.com/ and has more information and functionality available than the Legacy dashboard.

No Bundle or Spark Products

At this time, the 2024-02-21 version does not support the Bundle or Spark products.

Interval Data

Starting on May 29, 2024, the 2024-02-21 version will support interval data. Please reach out to your Customer Success Manager, Account Manager, or the Support team to learn more about coverage.

API Conventions

  • CamelCase is now used for field names and not snake_case.
  • All IDs are now strings and are prefixed with an abbreviation of their type, e.g. crd_1eef7318-6580-de55-8e25-0e4a3284646f for a Credential or stm_1eefb551-be7e-dbd5-9574-029883dd0af8 for a Statement.

Credential and File Submissions

Legacy Plug versions2024-02-21
Only test credentials could be submitted through the API. All other submissions had to be made through Connect.All credentials can be submitted through the API or Connect.
No support for ad hoc extraction from files.
Supports uploading PDFs of bills for extraction.

client_user_id vs correlationId

The client_user_id feature has been renamed to correlationId, but functions the same: a correlationId may be provided when submitting a credential or uploading file, and is applied to any Accounts, Statements and Meters extracted from those sources. Most search endpoints support searching by correlationId. You can read more about correlationIds here.

Connect

Connect no longer has to be initialized with a "Connect Token", and Connect itself is available at a long lived url. If you'd like to attach a correlationId when submitting a credential, that is now done through a query parameter.

The "Tariff Select" mode in Legacy Connect is not available in the 2024-02-21 version.

API Keys

API keys are still managed through the Dashboard. Legacy Plug API keys and access tokens are not usable with the 2024-02-21 version, and vice versa.

API keys can no longer have their secret rotated while preserving the client ID. If you need to rotate API keys, we recommend creating a new key, updating your code to use the new ID and secret, and then deleting the old key.

Improved Searching

Legacy Plug2024-02-21
List endpoints only support filtering by client_user_id, updated_after and updated_before and sorting by updated_at.List endpoints support filtering and sorting on many different fields. The exact fields depend on the specific resource being listed.

Sandbox Mode

Legacy Plug2024-02-21
Both demo and real accounts are supported in the sandbox.Only demo accounts are supported in the sandbox.
Live and sandboxed requests are made against api.arcadia.comLive requests are made against api.arcadia.com and sandbox requests are made against sandbox.api.arcadia.com

Webhook Endpoints

Legacy Plug2024-02-21
Allows for multiple webhook endpoints, both live and sandboxed. Each endpoint has it's own signing key for signatures.
Limited to one live and one sandboxed webhook endpoint. Signed webhooks are on the roadmap but not yet supported.

Webhooks

Note that this table excludes webhooks specific to Bundle, interval data, and the Tariff Select Mode in Connect. See this documentation for additional information on Plug 2 webhooks.

Legacy Plug2024-02-21
type: utility_credential_verifiedresource: CREDENTIAL
eventType: REAL_TIME_CREDENTIAL_VALIDATION_SUCCESS or STATUS_CHANGE
type: utility_credential_rejectedresource: CREDENTIAL
eventType: REAL_TIME_CREDENTIAL_VALIDATION_FAILURE or STATUS_CHANGE
type: utility_credential_revokedresource: CREDENTIAL
eventType: STATUS_CHANGE
type: utility_credential_verification_errorresource: CREDENTIAL
eventType: REAL_TIME_CREDENTIAL_VALIDATION_FAILURE or STATUS_CHANGE
type: utility_accounts_discoveredresource: ACCOUNT
eventType: STATUS_CHANGE
type:utility_accounts_discovery_errorn/a
type: utility_account_updatedn/a
type: historical_utility_statements_discoveredresource: STATEMENT
eventType: NEW_DATA_AVAILABLE
type:new_utility_statement_availableresource: STATEMENT
eventType: NEW_DATA_AVAILABLE
type: historical_utility_intervals_discoveredresource: METER
eventType: STATUS_CHANGE
type: new_utility_intervals_availableresource: METER
eventType: EXISTING_DATA_UPDATED

New Features

Expanded Service Types

The Legacy Plug API only worked with electricity providers, but 2024-02-21 supports a variety of service types, including natural gas, lighting, water, sewer, irrigation, steam and more.

Data Quality Audits

Legacy Plug had limited audits in place to ensure data quality. The 2024-02-21 version has many detailed audits in place to ensure data quality before Statements are delivered.

Providers Endpoints

The List Providers endpoint is now available to determine what Providers are supported by Plug.

Download Data from Arcadia

Through the API and Dashboard, users can request CSV or JSON downloads of their Statement, Meter and Site data.

Updated about 1 month ago