New Features

API Versioning

The Plug API uses a dated version scheme (YYYY-MM-DD). Using a version scheme allows Arcadia to release breaking changes without breaking your integration or requiring you to make updates before a certain time. Check out the Arc Platform API Versioning Guide for more information.

Sandbox Mode

The Plug API Sandbox mode allows you to learn how the Arc Platform works and test your integration without having or using real utility credentials. Check out the Arc Sandbox Mode Guide for more information.

Differences

Authentication

Legacy Utility Cloud	Plug API
Uses a bespoke authentication framework.	Fully compliant with OAuth 2.0 specs.
To authenticate with the API and the Console, you can use the same username and password pair.	API keys are issued at the organization level. One organization can have multiple API keys. - To authenticate with the API, you need to use API Keys. - To authenticate with the Dashboard, you need to use your email and password.
Both Console and API authentication is user-specific. You will be able to get user-specific events for changes made via both the Console and the API. For example, when John Smith updates a credential via either the API or via Console. You will be able to get an event that tells you the credential is updated by John Smith.	Dashboard authentication is user-specific, while API authentication is not. This means, you will only be able to get user-specific events when the change is made via the Dashboard. For example, when John Smith updates a credential via the API. You will not be able to know that it was John Smith who updated the credential.

API Headers

For the Plug API, you are required to specify an additional Arc-Version header:

curl --request GET  
     --url '<https://api.arcadia.com/plug/credentials?page=0&size=20'>  
     --header 'Arc-Version: 2023-08-07'

Check out the Arc Platform API Versioning Guide for more information.

Hypertext Application Language (HAL) Conventions

The Plug API no longer conforms to HAL. As a result, HATEOAS links are removed and we no longer wrap embedded resources under an _embedded key.

Expressing Supported Service Types

Legacy Utility Cloud	Plug API
We use the `serviceType` field to indicate the commodity type. In terms of data quality commitments, we treated all commodities equally.	We categorize all commodities into two classifications: 1. Core 2. Supplemental (Guide for more information on how we handle Services Types) We use the `serviceType` field to indicate the commodity type and the `serviceTypeClassification` field to indicate the classification for the service type.

Expressing `providerClassification`

We updated how we refer to the different classifications to be more consistent and more aligned with industry norms.

Legacy Utility Cloud	Plug API
`MAIN` and `PRIMARY`	`PUBLISHER`
`ADDITIONAL` and `SECONDARY`	`PASS_THROUGH`

For more information on how these classifications work, please refer to the Arc Data Model Guide.

Expressing Statuses

For a full status mapping, please refer to the Status Mapping Guide.

Legacy Utility Cloud Plug API

For credential, account, and meter, we use:
- status (string) field to communicate the high level status of the resource.
- statusDetail(string) field to communicate any reasons we can share for the status.

For file, we use:
- status (string) field to communicate the high level status of the resource.
- fileDetail(array of string) field to communicate any reasons we can share about the reason for that status. For credential, account, file we use:
- status (string) field to communicate the high level status of the resource.
- statusDetail (string for credential and account; array of string for file) field to communicate any reasons we can share for the status.
- isCustomerActionRequired (boolean) field to explicit indicate whether there's additional action you can take to ensure the resource is successfully processed.

- We will no longer have statuses for meter

Legacy Utility Cloud	Plug API
For `credential`, `account`, and `meter`, we use: - `status` (`string`) field to communicate the high level status of the resource. - `statusDetail`(`string`) field to communicate any reasons we can share for the status. For `file`, we use: - `status` (`string`) field to communicate the high level status of the resource. - `fileDetail`(array of `string`) field to communicate any reasons we can share about the reason for that status.	For `credential`, `account`, `file` we use: - `status` (`string`) field to communicate the high level status of the resource. - `statusDetail` (`string` for `credential` and `account`; array of `string` for `file`) field to communicate any reasons we can share for the status. - `isCustomerActionRequired` (`boolean`) field to explicit indicate whether there's additional action you can take to ensure the resource is successfully processed. - We will no longer have statuses for `meter`

Handing Correlation IDs for Credentials

Legacy Utility Cloud	Plug API
You can submit the same credentials multiple times as long as the `correlationId` is unique. If the `correlationId` matches an existing one, you will get a 409 already exists error.	If you submit the same credentials more than once, even with a different `correlationId`, you will get a 409 already exists error.

The Statement Endpoint

Legacy Utility Cloud Plug API

The statement resource in the GET List Statement endpoint response and the GET Retrieve Statement endpoint response are different. The statement resource in the GET List Statement endpoint response and the GET Retrieve Statement endpoint response will be the same.

For readability and an easier onboarding experience, the /statement endpoint will default to a summarized view of the statement object, while the /statements/details endpoint will provide the non-truncated view of the statement object. We believe that the /statement endpoint response should be sufficient for most utility data use cases.

Legacy Utility Cloud	Plug API
The statement resource in the GET List Statement endpoint response and the GET Retrieve Statement endpoint response are different.	The statement resource in the GET List Statement endpoint response and the GET Retrieve Statement endpoint response will be the same. For readability and an easier onboarding experience, the `/statement` endpoint will default to a summarized view of the statement object, while the `/statements/details` endpoint will provide the non-truncated view of the statement object. We believe that the `/statement` endpoint response should be sufficient for most utility data use cases.

Searching via API

Legacy Utility Cloud	Plug API
To obtain a list of searchable fields for a resource, you will need to query the respective Search endpoints.	The list of searchable fields is directly accessible under the search parameter in the query parameters section for a certain field in the API Reference.

Webhooks

Legacy Utility Cloud	Plug API
Arcadia will only send webhooks for status transitions that require customer action.	Arcadia will send webhooks for all status transitions for all stateful resources (i.e. credential, account, file, deletion, download).

Check out the Webhooks Guide for more information.

Error Handling

Error response has been updated to be more consistent and informative in the following ways:

Show all applicable errors in a response
Specify which request parameter caused the error
Categorize errors into a set list of error types:
- conflict
- internalServerError
- invalidParameter
- notFound
- tooManyRequests
- forbidden
- methodNotAllowed

API Field Naming Conventions

For better readability, Arcadia introduced the following naming convention for API fields:

ID handling:
- The entityId field in the Legacy Utility Cloud API has been renamed to id
- id are prefixed with an abbreviation to indicate the resource it identifies with the following abbreviations:
  - Account: act_
  - Credential: crd_
  - Deletion Log: del_
  - Download: dwl_
  - Error: err_
  - File: fil_
  - Meter: mtr_
  - Organization: org_
  - Payment: pmt_
  - Provider: prv_
  - Statement: stm_
  - Webhook: whk_
  - Site: sit_
  - Usage: usg_
  - User: usr_
- All ids are UUIDs except for error ids. Error ids are NanoIDs.
  📘
  Migrating from legacy Utility Cloud to Plug API
  On Plug, the IDs of your resources will be updated with the above prefix. For example, if an account ID in legacy Utility Cloud is 1eedaa3e-bccb-d579-8f8d-6a861e9050ca, in Plug, the ID of that same resource would be act_1eedaa3e-bccb-d579-8f8d-6a861e9050ca.
AsPrinted is suffixed for all fields we present exactly as they are seen on the bill.
- For example, the chargeActualName field in the Legacy Utility Cloud API has been renamed to chargeActualNameAsPrinted in the Plug API.
Field names that contain abbreviations are fully spelled out.
- For example, the podNumber field in the Legacy Utility Cloud API has been renamed as will be named pointOfDeliveryNumber in the Plug API.
Date is suffixed to all date fields without a time component.
For example, the periodStart field in the Legacy Utility Cloud API has been renamed to periodStartDate in the Plug API.
At is suffixed to all date-time fields with a time component.
- For example, the createdDate field in the Legacy Utility Cloud API has been renamed to createdAt in the Plug API.
is is prefixed for all boolean fields.
- For example, the supportsThirdPartyPortal field in Legacy Utility Cloud API has been renamed to isThirdPartyPortalSupported in the Plug API.