Utility Cloud to Plug API Migration Guide

Document Version: 1.0
Plug API Version: 2024-02-21 (Most recent)
Last Updated: 2026-04-07

This document is the comprehensive migration reference for customers moving from the Utility Cloud (UC) API to the Plug API. It covers every aspect of the migration including authentication, endpoint mapping, field-by-field resource mappings, status/enum changes, error handling, and behavioral differences.

The database is the same, meaning that customers do not have to resubmit their credentials to migrate. All their data is accessible already.

Table of Contents

1. Overview & Quick Reference
2. Authentication & Authorization
3. Required Headers
4. Base URL & Endpoint Mapping
5. Response Format Changes
6. ID Format Changes
7. Field Naming Convention Changes
8. Resource Field Mappings
   • Account
   • Credential
   • Statement
   • Meter
   • Site
   • File
   • Webhook
   • Payment
   • Usage
   • Charge
   • Tariff
   • Provider
   • Organization
   • Download Request
   • Deletion Log
   • Event Resources
   • Address
   • Custom Data
9. Status & Enum Value Mappings
10. Event Type Mappings
11. Webhook Changes
12. Error Handling
13. Pagination, Sorting & Filtering
14. Behavioral Changes
15. New Plug-Only Features
16. Request Body Changes
17. Migration Checklist

1. Overview & Quick Reference

What is Changing?

The Plug API is a modernized replacement for the Utility Cloud (UC) API. While both APIs expose the same underlying data, the Plug API introduces:

• Standardized OAuth 2.0 authentication with organization-level API keys
• Dated API versioning via the Arcadia-Version header
• Removal of HATEOAS/HAL — no more _embedded wrappers or _links objects
• Consistent naming conventions — prefixed IDs, At timestamp suffixes, is boolean prefixes
• Structured error responses — typed errors with parameter-level detail
• Expanded webhooks — notifications for all status transitions, not just action-required ones
• New resources — intervals, discovered statements, expected accounts, alternate access and more

Summary of Breaking Changes

2. Authentication & Authorization

Utility Cloud (Legacy)

• Authentication method: Bespoke framework with unified username/password
• The same credentials were used for both the API and the Console (dashboard)
• User-specific audit trails available for both API and Console changes

Plug API (New)

• Authentication method: Fully compliant with OAuth 2.0
• Organization-level API keys: Multiple API keys can be created per organization
• Separate credentials: Dashboard requires email/password; API requires API keys

Migration Action

1. Obtain new OAuth 2.0 API keys for your organization from the Arcadia Dashboard
2. Update your API client to use Bearer token authentication
3. If you are using service accounts for API access, create new API keys to replace them and then delete the existing service accounts to avoid stale credentials.
4. Update all users to login with their email address instead of a username. Plug enforces one user per email address.
5. If your organization has multiple users sharing the same email, contact your CSM team to consolidate accounts before migrating. Duplicate email logins must be resolved prior to migration.

3. Required Headers

New Required Header

The Plug API introduces dated API versioning. You must include the Arcadia-Version header in every request:

Arcadia-Version: 2024-02-21

This enables Arcadia to introduce breaking changes in future versions without forcing immediate client updates.

Sandbox Mode Header

The Plug API supports sandbox mode via a request header:

X-Sandbox: true

Set this header to true to operate in sandbox mode. Default is false (production mode).

Content-Type Changes

Example Requests

Utility Cloud:

curl --request GET \
     --url 'https://api.urjanet.com/utility/accounts?page=0&size=20' \
     --header 'accept: application/json'

Plug API:

curl --request GET \
     --url 'https://api.arcadia.com/plug/accounts?page=0&size=20' \
     --header 'Arcadia-Version: 2024-02-21' \
     --header 'accept: application/json'

4. Base URL & Endpoint Mapping

Base URL Change

All endpoint paths below are relative to the base URL. For example, GET /accounts means:

• UC: GET https://api.urjanet.com/utility/accounts
• Plug: GET https://api.arcadia.com/plug/accounts

Common Endpoints (Present in Both APIs)

The relative paths are the same across both APIs. Only the base URL changes.

New Plug-Only Endpoints

These endpoints exist only in the Plug API and have no UC equivalent.

Removed/Changed UC Endpoints

5. Response Format Changes

HATEOAS/HAL Removal

The most significant structural change is the removal of HATEOAS (Hypermedia as the Engine of Application State) and HAL (Hypertext Application Language) formatting.

Utility Cloud response (HAL+JSON):

{
  "_embedded": {
    "accounts": [
      {
        "entityId": "1eedaa3e-bccb-d579-8f8d-6a861e9050ca",
        "accountNumber": "123456",
        "enabled": true,
        "createdDate": "2024-01-15T10:30:00Z",
        "_links": {
          "self": {
            "href": "https://api.urjanet.com/utility/accounts/1eedaa3e-bccb-d579-8f8d-6a861e9050ca"
          },
          "statements": {
            "href": "https://api.urjanet.com/utility/accounts/1eedaa3e-bccb-d579-8f8d-6a861e9050ca/statements"
          }
        }
      }
    ]
  },
  "_links": {
    "self": { "href": "https://api.urjanet.com/utility/accounts?page=0&size=20" },
    "next": { "href": "https://api.urjanet.com/utility/accounts?page=1&size=20" }
  },
  "page": {
    "size": 20,
    "totalElements": 150,
    "totalPages": 8,
    "number": 0
  }
}

Plug API response (plain JSON):

{
  "content": [
    {
      "id": "act_1eedaa3e-bccb-d579-8f8d-6a861e9050ca",
      "accountNumber": "123456",
      "isStatementsProductActive": true,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 150,
    "totalPages": 8,
    "number": 0
  }
}

Key Structural Differences

Statement Endpoint Split

In UC, the statement list and single-get endpoints returned the same full structure. In Plug, statements are split:

Migration Action

1. Remove all code that parses _embedded wrappers — access content directly
2. Remove all code that follows _links for navigation — use page metadata instead
3. Remove all code that reads _links from individual resources
4. Update your Content-Type expectations from application/hal+json to application/json
5. If you need full statement details in list calls, use GET /statements/details instead of GET /statements

6. ID Format Changes

All resource IDs in the Plug API are prefixed with a resource-type identifier.

ID Prefix Table

Note: Additional resource ids can be added down the road for new Entities and would not be considered breaking.

ID Field Name Change

The field name itself also changes:

Note: Error IDs use NanoIDs (not UUIDs) and follow the format err_<nanoid>.

Migration Action

1. Update all ID parsing logic to handle the prefix format
2. Replace references to entityId with id
3. When sending IDs in requests (path parameters, request bodies), use the prefixed format
4. If you store IDs externally, plan for the prefix addition

7. Field Naming Convention Changes

The Plug API applies systematic naming rules across all resources:

Naming Rules

Common Field Renames Across All Resources

8. Resource Field Mappings

This section provides field-by-field mapping tables for every resource type. Fields marked New exist only in Plug. Fields marked Removed exist only in UC.

8.1 Account

8.2 Credential

8.3 Statement

The Plug API splits statements into Summary and Detailed views.

Statement Summary (List endpoint: GET /statements)

Statement Detailed (Single get: GET /statements/{id} or list: GET /statements/details)

Includes all Summary fields plus:

8.4 Meter

8.5 Site

8.6 File

8.7 Webhook

8.8 Payment

8.9 Usage

8.10 Charge

8.11 Tariff

8.12 Provider

8.13 Organization

8.14 Download Request

8.15 Deletion Log

8.16 Event Resources

Event resources (Account, Credential, Meter, File, Site) all follow the same pattern:

8.17 Address

8.18 Custom Data

The custom data structure is identical in both APIs:

{
  "customData": {
    "label1": "value1",
    "label2": "value2"
  }
}

Custom data field names are configured at the organization level using accountCustomData1Name through accountCustomData25Name (accounts) and meterCustomData1Name through meterCustomData10Name (meters).

9. Status & Enum Value Mappings

9.1 Account Status

9.2 Account Status Detail

9.3 Credential Status

9.4 Credential Status Detail

9.5 File Status

Note: Files can go back and be reprocessed after initial success.

9.6 Webhook Status

9.7 Provider Classification

9.8 Deletion Log Status

9.9 Download Status

9.10 Address Type

Why the rename? In UC, RAW meant "no address processing was applied — this is the address exactly as the customer provided it." Plug renamed this to CUSTOMER_PREFERRED to better communicate what the value actually represents: this is the address format the customer wants used. The underlying behavior is identical — no normalization is performed. The name was changed because "raw" implied the data was incomplete or unfinished, when in reality the customer intentionally provided it this way (e.g., when creating a site via the API).

9.11 Data Ingestion Method (New in Plug)

Maps from UC's StatementOrigin:

9.12 Service Type Classification (New in Plug)

New classification that categorizes service types:

9.13 Connection Health (New in Plug)

Derived from credential status and alternate access information:

9.14 MFA Opt-Out Status (New in Plug)

MFA Opt-Out Guide

Note : We can add values to these ENUMs any time without it being considered breaking.

10. Event Type Mappings

10.1 Account Events

10.2 Credential Events

10.3 File Events

10.4 Meter Events

10.5 Site Events

11. Webhook Changes

Behavioral Change

Webhook Event Type Mapping

New Webhook Resource Field

The Plug API adds a resource field to webhook notifications that identifies which resource type triggered the webhook, making it easier to route webhook processing.

Migration Action

1. Update webhook event type parsing to handle new values
2. If you filter webhooks by event type, update your filters
3. Expect significantly more webhook volume (all status transitions, not just action-required)
4. Handle the new resource field for routing

12. Error Handling

Error Response Format

Utility Cloud:

{
  "message": "Bad request",
  "exception": null,
  "path": "/accounts/123",
  "status": 400,
  "error": "Detailed error message"
}

Plug API:

{
  "errors": [
    {
      "type": "invalidParameter",
      "message": "Human-readable error description",
      "param": "accountNumber",
      "details": {
        "errorId": "err_abc123def456"
      }
    }
  ]
}

Error Type Values

Key HTTP Status Code Changes

Key Differences

1. Multiple errors: Plug returns ALL applicable errors in a single response (e.g., multiple validation failures), not just the first one
2. Parameter identification: The param field tells you exactly which parameter caused the error
3. Error IDs: Every error includes a unique errorId (NanoID format: err_*) for support reference
4. Structured types: Errors are categorized by type instead of relying on HTTP status alone

Migration Action

1. Update error parsing to read from errors array instead of flat fields
2. Handle multiple errors per response
3. Use type field for error categorization instead of parsing message
4. Update any hardcoded HTTP status expectations (especially 400→404 for not-found)
5. Log errorId from details for support escalations

13. Pagination, Sorting & Filtering

Pagination

Pagination works the same way in both APIs:

Max page x size value can be 10000.

Response metadata:

{
  "page": {
    "size": 20,
    "totalElements": 150,
    "totalPages": 8,
    "number": 0
  }
}

Sorting

Sorting works the same way in both APIs:

GET /accounts?sort=createdAt,desc
GET /accounts?sort=accountNumber,asc&sort=createdAt,desc

Filtering / Search (RSQL)

Both APIs use the same RSQL query language. For full search syntax, operators, and encoding details, see the Plug API Searching Documentation.

Key Differences

1. Search field values must use Plug enum values — e.g., search=status==CONNECTION_SUCCESS not search=status==OK
2. Date format in search: yyyy-MM-dd (ISO_LOCAL_DATE)
3. The /searchableFields endpoint is removed — refer to API documentation instead
4. Be sure to URL encode the searches or it may not work as you intend

Searching Guide

14. Behavioral Changes

14.1 Credential Deduplication

Note : Clean up any lingering duplicate credentials as it makes for dirty data.

14.2 isCustomerActionRequired Flag

The Plug API adds an isCustomerActionRequired boolean to Account, Credential, and File resources. This flag indicates whether the customer needs to take action to resolve the current status.

Previously in UC, you had to interpret specific statusDetail values to determine if action was needed. Now the Plug API provides this explicitly.

14.3 connectionHealth on Credential

The Plug API adds a connectionHealth field that provides a simplified view of the credential's connection state, derived from the credential status and any alternate accesses:

• CONNECTION_SUCCESS — credential or alternate access is working
• CONNECTION_IN_PROGRESS — credential or alternate access setup is in progress
• CONNECTION_FAILURE — credential connection has failed
• CONNECTION_DEACTIVATED — credential is deactivated

Note: If no alternate access exists, the connection health will be the same as the Credential Status

14.4 Statement Versioning

The Plug API introduces statement versioning:

14.5 Service Types Changed from Strings to Objects

In UC, serviceTypes on an account was a List<String>. In Plug, it's a List<PublicServiceTypeResource>, which includes the service type name and its classification (CORE or SUPPLEMENTAL).

14.6 Meter Status Removed

UC had a meterStatus field on meters. This has been removed in Plug. Instead, meters have:

• status — MeterIntervalStatus (for interval data status)
• statusDetail — MeterIntervalStatusDetail

14.7 Account References on Meters Changed

UC used accountIds and accountNumbers (flat lists of strings). Plug uses an accounts list of PublicEmbeddedAccountResource objects, which provide richer information about each associated account.

14.8 correlationIds is Now a List

In UC, correlationId was a single string. In Plug, correlationIds is a List<String>, supporting multiple correlation IDs per resource. This can contain multiple values when correlation IDs are inherited from both a Credential and a File associated with the same resource.

14.9 finalBillNotice Changed to Boolean

14.10 Currency Code Added to Statements

Statements now include a currencyCode field (enum) for explicit currency identification.

15. New Plug-Only Features

API Docs

These features are available only in the Plug API and have no UC equivalent:

15.1 Intervals & Normalized Intervals

• GET /intervals — Raw interval data for meters
• GET /normalizedIntervals — Normalized interval data
• Associated meter fields: earliestIntervalAt, latestIntervalAt, isIntervalsProductActive, latestIntervalsCheckedAt

15.2 Expected Accounts

• GET /expectedAccounts — Track expected but not yet discovered accounts
• POST /expectedAccounts — Create expected accounts
• Used for monitoring data discovery progress

15.3 Discovered Statements

• GET /discoveredStatements — Track statement discovery before full processing
• Links to statements via discoveredStatementId

15.4 Providers & Service Types Directory

• GET /providers — Browse the provider directory
• GET /serviceTypes — List available service types

15.5 Arcadia Connect

• POST /credentials/encodedConnectUrl — Generate encoded Arcadia Connect URLs
• Used for embedded credential capture flows

15.6 MFA Support

• POST /credentials/{id}/mfa — Submit MFA method selection
• POST /credentials/{id}/otp — Submit one-time password
• multiFactorAuthenticationOptOutStatus and lastSuccessfulMultiFactorAuthenticationOptOutAt fields on credentials

15.7 Alternate Access

• Credentials now include an alternateAccesses list showing alternative data access methods
• Each alternate access has its own status and type

15.8 Webhook Testing

• POST /webhooks/{id}/test — Send a test webhook to verify your endpoint

15.9 Sandbox Mode

• X-Sandbox: true header enables sandbox mode
• Separate data environment for testing without affecting production data
• Sandbox/production conflicts are detected and return 409

16. Request Body Changes

16.1 Create Account

16.2 Update Account

16.3 Create Credential

16.4 Create Site

All UC fields are supported plus new building detail fields:

16.5 Create Meter

16.6 Download Requests

Download request bodies remain largely the same. Key changes:

17. Migration Checklist

Use this checklist to track your migration progress:

Pre-Migration

• Obtain OAuth 2.0 API keys from the Arcadia Dashboard
• Review all breaking changes in this document
• Identify all UC API endpoints your application uses
• Inventory all field references in your codebase

Authentication

• Update authentication to use OAuth 2.0 Bearer tokens
• Update base URL from https://api.urjanet.com/utility/ to https://api.arcadia.com/plug/
• Add Arcadia-Version: 2024-02-21 header to all requests
• Update Content-Type expectations from application/hal+json to application/json
• Add X-Sandbox header support if using sandbox mode

Response Parsing

• Remove _embedded wrapper parsing — use content array directly
• Remove _links navigation parsing — use page metadata for pagination
• Remove per-resource _links parsing
• Update statement list parsing for summary format (or use /statements/details)

ID Handling

• Update ID field references from entityId to id
• Handle prefixed IDs (e.g., act_uuid, crd_uuid)
• Update any stored IDs or ID comparison logic
• Update IDs in request bodies and path parameters to use prefix format

Field Names

• Update all timestamp fields (createdDate → createdAt, etc.)
• Update all date-only fields (periodStart → periodStartDate, etc.)
• Update boolean fields (enabled → isActive/isStatementsProductActive, etc.)
• Update "actual name" fields to "as printed" pattern
• Update abbreviations (podNumber → pointOfDeliveryNumber, etc.)
• Remove references to providerName / providerAlias — use provider.name

Status & Enum Values

• Update account status value handling (e.g., OK → CONNECTION_SUCCESS)
• Update account status detail handling (17 UC → 10 Plug values)
• Update credential status value handling
• Update credential status detail handling (34 UC → 29 Plug values)
• Update file status handling (REJECTED → FAILURE)
• Update webhook status handling (ERROR → FAILURE)
• Update provider classification (PRIMARY/SECONDARY → PUBLISHER/PASS_THROUGH)
• Update address type handling (RAW → CUSTOMER_PREFERRED)
• Handle new isCustomerActionRequired boolean
• Handle new connectionHealth field on credentials

Event Types

• Update account event type parsing
• Update credential event type parsing
• Update file event type parsing
• Update meter event type parsing
• Update site event type parsing

Webhooks

• Update webhook event type handling (e.g., NEW_STATEMENT → NEW_DATA_AVAILABLE)
• Prepare for increased webhook volume (all status transitions)
• Handle the new resource field on webhooks
• Update webhook filtering logic if applicable

Error Handling

• Update error response parsing to use errors array format
• Handle multiple errors per response
• Use type field for error categorization
• Update HTTP status expectations (especially 400 → 404 for not-found)
• Log errorId from error details for support

Request Bodies

• Update account create/update request fields
• Update credential create request fields
• Update IDs in request bodies to use prefix format
• Update any enum values sent in requests to use Plug values

Search & Filtering

• Update RSQL search values to use Plug enum values
• Update sort field names to Plug naming convention
• Remove calls to /searchableFields endpoints

Post-Migration

• Run integration tests against Plug API
• Verify pagination works correctly with new response format
• Test error handling with invalid requests
• Verify webhook reception and parsing
• Monitor for increased webhook volume
• Evaluate new Plug-only features for adoption

Appendix: Quick Reference Card

Response Format

UC:   { "_embedded": { "resources": [...] }, "_links": {...}, "page": {...} }
Plug: { "content": [...], "page": {...} }

ID Format

UC:   "entityId": "1eedaa3e-bccb-d579-8f8d-6a861e9050ca"
Plug: "id": "act_1eedaa3e-bccb-d579-8f8d-6a861e9050ca"

Error Format

UC:   { "message": "...", "status": 400, "error": "..." }
Plug: { "errors": [{ "type": "invalidParameter", "message": "...", "param": "...", "details": { "errorId": "err_..." } }] }

Base URL

UC:   https://api.urjanet.com/utility/
Plug: https://api.arcadia.com/plug/

Required Headers

Arcadia-Version: 2024-02-21
Authorization: Bearer <token>
Content-Type: application/json
X-Sandbox: true|false  (optional, default: false)