HomeGuidesAPI ReferenceChangelog
Log In
Guides

Sandbox Mode

Learn and test the Arc Platform without real provider credentials with the Arc Sandbox.

👍

Accessing Arc Sandbox Mode

You need to have access to the Dashboard in order to use the Arc Sandbox. To get access to the Dashboard, you can:

  1. Ask an existing Dashboard user in your organization to add you as a Dashboard user.
  2. Reach out to your Customer Success Manager, Account Manager, or the Arcadia Support team to get access to the Dashboard.

Overview

The Arc API can be used in two modes, live or sandbox. You can indicate which mode you want to use in two ways:

Via the API

You can specify the mode you prefer by using the sandbox domain, as follows:

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

Via the Dashboard

You can toggle on/off the "Sandbox mode" toggle:

Thesandbox mode is great for:

  • Learning how the API works
  • Learning the scenarios you need to account for during development
  • Setting up continuous integration tests for your integration

Testing Scenarios

Arcadia provides a variety of sandbox testing scenarios for you to test common possible scenarios related to:

  • Connecting provider credentials
  • Receiving and handling data structures from different types of statements
  • Receiving and handling webhooks

As the Arc sandbox mode is designed to mirror live as much as possible, to test different scenarios, you would need to:

  1. Select a provider.

  2. Set up your the webhook url for sandbox mode via

    1. Dashboard: Enter the webhook url in the sandbox field.

    2. API: Update the sandboxWebhookUrl field using PATCH Update Current Organization

  3. Select a sandbox credential depending on the scenario you want to test and share the credential with Arcadia via

    1. Connect: Enter the username and password in Connect
    2. API: Create a Credential with the username and password
  4. Receive webhook notifications

  5. (When data is avaliable) Obtain utility data via

    1. Dashboard: Navigate to the Account/Meter tabs to view data.
    2. API: Use GET Statement or other endpoints to view data.

You can test a scenario by using a specific sandbox credential (a username and password combination. Data will only be available when passwords are valid and when the scenario has data available. When data is available, you can retrieve 12 months of statement history for that credential.

Sandbox Providers

We have three different sandbox providers. Any of these can be used with a valid sandbox scenario username and password combination.

  • Arc Municipal Service: A standard provider supported by the Plug API with real time credential validation (RTCV) enabled.
  • Arc Non-RTCV Municipal Service: A standard provider supported by the Plug API without real time credential validation (RTCV) enabled.
  • ArConsolidated Edison: A provider that mocks the behavior of Consolidated Edison. For more info, see the ConEd Testing section.

The only difference between the Arc Municipal Service and Arc Non-RTCV Municipal Service providers is that Arc Non-RTCV will skip any credential validation behaviors. This means, if you are testing with Connect, there will be no indication for whether the credential submission was successful and no REAL_TIME_CREDENTIAL_VALIDATION_SUCCESS or REAL_TIME_CREDENTIAL_VALIDATION_FAILURE webhooks sent. Any validation timeout related behaviors indicated by the password selected will be ignored.

👍

Test the Arc Platform without using real utility credentials

Testing Connections with non-ConEd Providers

Like a real utility credential, a sandbox utility credential consists of a username and a password. To select your desired testing scenario, you can use the username to indicate the variation of mock data you would like to receive and use the password to indicate the credential connection status and status detail.

🚧

sandbox Utility Credentials will be automatically disabled after the first data extraction attempt.

You can trigger a new statement to be generated for that credential manually by using the POST Generate New Statement endpoint.

Mock Data Scenarios (usernames)

UsernameMock data Scenario
ARC_MOCK_RESI_SINGLE_ELEC_SINGLE_METEROne electric account with one electric meter
ARC_MOCK_RESI_SINGLE_ELEC_MULTI_METEROne electric account with three electric meters
ARC_MOCK_RESI_MULTI_ELEC_SINGLE_METERThree electric accounts each with one distinct electric meter
ARC_MOCK_RESI_SINGLE_GAS_SINGLE_METEROne gas account with one gas meter
ARC_MOCK_RESI_SINGLE_GAS_MULTI_METEROne gas account with three gas meters
ARC_MOCK_RESI_SINGLE_ELEC_SINGLE_GAS_SINGLE_METERSOne electric account with one electric meter and one gas account with one gas meter
ARC_MOCK_RESI_COMBINED_ELEC_GAS_SINGLE_METERSOne combined electric and gas account with one electric meter and one gas meter
ARC_MOCK_RESI_SINGLE_WATER_SINGLE_METEROne water account with one water meter
ARC_MOCK_RESI_SINGLE_WATER_MULTI_METEROne water account with three water meters
ARC_MOCK_RESI_SINGLE_ELEC_SINGLE_GAS_SINGLE_WATER_SINGLE_METERSOne electric account with one electric meter, one gas account with one gas meter, and one water account with one water Meter
ARC_MOCK_RESI_NO_ACCOUNTS*No statements or accounts are associated with this credential
ARC_MOCK_RESI_CLOSED*One closed electric account with one electric meter.

*New statements cannot be triggered on these scenarios.

Sandbox Passwords

The following passwords control the credential status of sandbox Utility Credential submission. Any other password will be treated as invalid.

PasswordResultCredential status / statusDetail
VERIFIEDThe credential was verified within the Connect RTCV timeoutCONNECTION_SUCCESS / LOGIN_AND_DATA_DISCOVERY_SUCCESSFUL
REJECTEDThe credential was rejected within the Connect RTCV timeoutCONNECTION_FAILURE/ INVALID_CREDENTIALS
TIMEOUT_VERIFIEDThe credential was verified after the Connect timeoutCONNECTION_SUCCESS / LOGIN_AND_DATA_DISCOVERY_SUCCESSFUL
TIMEOUT_REJECTEDThe credential was rejected after the Connect timeoutCONNECTION_FAILURE/ INVALID_CREDENTIALS
TEMPORARY_ERRORAn error occurred (like the provider website was down) but Arc will automatically retryCONNECTION_IN_PROGRESS/ PROVIDER_WEBSITE_INACCESSIBLE
FATAL_ERROR_ACCOUNT_BLOCKEDWe couldn't verify credential because a user action is required (the account is blocked for now or we’ve hit a limit on retry attempts).CONNECTION_FAILURE/ INVALID_CREDENTIALS
FATAL_ERRORGeneral error state reached before the Connect timeout was hit.CONNECTION_IN_PROGRESS/ISSUE_UNDER_REVIEW
FATAL_ERROR_TIMEOUTGeneral error state reached before the Connect after timeout was hit and Connect was closed.CONNECTION_IN_PROGRESS/ISSUE_UNDER_REVIEW

After a valid sandbox Utility Credential is submitted, Arcadia will proceed to retrieve 12 months of Statement history for the credential and disable the credential.

"New" statements become available for all sandbox providers on the 20th of each month. If you want new Statements for a credential, you can use the POST Generate New Statement endpoint. If new statements became available since the Credential was first disabled, those will be retrieved first. Otherwise, statements with future dates will be retrieved.

Example: Sandbox Credential Submission via API

To submit a Credential with one Electric Account:

curl -X POST \
	--url "https://sandbox.api.arcadia.com"
	-H "Authorization: Bearer <your_token_here>"
  -H "Arc-Version: 2024-02-21"
	-H "Content-type: application/json"
	-d '{
		"providerId": "prv_d06d8bc9-495b-4ba6-b281-b40934cd898e",
         "username": "ARC_MOCK_RESI_MULTI_ELEC_SINGLE_METER",
         "password": "VERIFIED",
         "interactive": true,
         "correlationId": "sandbox_test"
      }'

Response:

{
  "correlationId": "sandbox_test",
  "createdBy": "user.name",
  "createdDate": "2023-06-29T22:34:57.949+00:00",
  "enabled": true,
  "id": "crd_6e60787c-ed56-4336-b52d-01a6e3ac0aae",
  "lastModifiedBy": "user.name",
  "lastModifiedDate": "2023-06-29T22:34:57.949+00:00",
  "nextScheduledRun": "2023-06-29T22:34:57.671+00:00",
  "provider": {
    "country": null,
    "id": "prv_d06d8bc9-495b-4ba6-b281-b40934cd898e",
    "providerName": "Arc Municipal Service",
    "supportsCredentialValidation": true,
    "website": ""
  },
  "providerName": "Arc Municipal Service",
  "runHistory": false,
  "status" : "CONNECTION_SUCCESS",
  "statusDetail" : "LOGIN_AND_DATA_DISCOVERY_SUCCESS",
  "totalAccounts": 0,
  "username": "ARC_MOCK_RESI_MULTI_ELEC_SINGLE_METER",
  "username2": null,
  "username3": null,
  "username4": null,
  "website": null,
  "thirdPartyPortal": false
}

Testing Connection with ConEd

Testing with ArConsolidated Edison works a little differently than regular providers by using submitted Account numbers rather than Credentials. Please note that the live API must be used for real ConEd Accounts and that the sandbox provider omits a few steps from the process - setting up the access portal and sending out an email enrollment request.

To start testing with the ArConslidated Edison provider:

  • If you are using the Dashboard, select ArConsolidated Edison in Connect and submit an account number from the "Mock Data Scenarios" table below.
  • If you are using the API, use the POST accounts endpoint against https://sandbox.api.arcadia.com with the ArConsolidated Edison providerId and an accountNumber from the "Mock Data Scenarios" table.

After the Account is submitted, a sandbox Third Party Portal will be created for the account and the account will be automatically enrolled if it matches one of our provided scenarios. The email approval step that real ConEd accounts require is skipped, and the account is scheduled to run in the next minute for data to be pulled.

Mock Data Scenarios

These Account numbers can be used to simulate real ConEd Accounts with various data scenarios

Account NumberMock Data Scenario
11235813010One electric account with one meter
11235813020One electric account with three meters
11235813030One gas account with one meter
11235813040One gas account with three meters
11235813050One combined electric and gas account with one electric meter and one gas mete
11235813060One closed electric account with one electric meter

Example: Account Submission via API

To submit an electric Account with one Meter:

curl --request POST \
     --url https://sandbox.api.arcadia.com/plug/accounts \
     --header 'Arc-Version: 2024-02-21' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your-token-here>' \
     --header 'content-type: application/json' \
     --data '
{
  "accountNumber": "11235813010",
  "providerId": "prv_1ee61fb9-89b3-dc96-a9f2-b67fc1b3860f"
}
'

Response:

{
  "accountNumber" : "11235813010",
  "createdAt" : "2024-02-21T01:41:41.439+00:00",
  "createdBy" : "user.name",
  "customData" : null,
  "firstExtractedAt" : null,
  "id" : "act_1eed05a5-c947-d06d-9bc7-baab5b793a60",
  "isCustomerActionRequired" : false,
  "isStatementsProductActive" : true,
  "lastModifiedAt" : "2024-02-21T01:41:41.439+00:00",
  "lastModifiedBy" : "user.name",
  "lastSuccessfulExtractionAt" : null,
  "latestNewStatementAt" : null,
  "latestStatementDate" : null,
  "nextExpectedPostDate" : null,
  "normalizedAccountNumber" : "11235813010",
  "prepaid" : false,
  "provider" : {
    "country" : "USA",
    "id" : "prv_1ee61fb9-89b3-dc96-a9f2-b67fc1b3860f",
    "name" : "ArConsolidated Edison",
    "supportsCredentialValidation" : true
  },
  "providerClassification" : "PUBLISHER",
  "serviceTypes" : [ ],
  "siteNames" : [ ],
  "status" : "CONNECTION_IN_PROGRESS",
  "statusDetail" : null,
  "summaryAccountId" : null,
  "summaryAccountNumber" : null,
  "type" : "NORMAL"
}