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:
- Ask an existing Dashboard user in your organization to add you as a Dashboard user.
- 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:
-
Select a provider.
-
Set up your the webhook url for
sandbox
mode via-
Dashboard: Enter the webhook url in the
sandbox
field. -
API: Update the
sandboxWebhookUrl
field using PATCH Update Current Organization
-
-
Select a sandbox credential depending on the scenario you want to test and share the credential with Arcadia via
- Connect: Enter the
username
andpassword
in Connect - API: Create a Credential with the
username
andpassword
- Connect: Enter the
-
Receive webhook notifications
-
(When data is avaliable) Obtain utility data via
- Dashboard: Navigate to the Account/Meter tabs to view data.
- 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)
Username | Mock data Scenario |
---|---|
ARC_MOCK_RESI_SINGLE_ELEC_SINGLE_METER | One electric account with one electric meter |
ARC_MOCK_RESI_SINGLE_ELEC_MULTI_METER | One electric account with three electric meters |
ARC_MOCK_RESI_MULTI_ELEC_SINGLE_METER | Three electric accounts each with one distinct electric meter |
ARC_MOCK_RESI_SINGLE_GAS_SINGLE_METER | One gas account with one gas meter |
ARC_MOCK_RESI_SINGLE_GAS_MULTI_METER | One gas account with three gas meters |
ARC_MOCK_RESI_SINGLE_ELEC_SINGLE_GAS_SINGLE_METERS | One electric account with one electric meter and one gas account with one gas meter |
ARC_MOCK_RESI_COMBINED_ELEC_GAS_SINGLE_METERS | One combined electric and gas account with one electric meter and one gas meter |
ARC_MOCK_RESI_SINGLE_WATER_SINGLE_METER | One water account with one water meter |
ARC_MOCK_RESI_SINGLE_WATER_MULTI_METER | One water account with three water meters |
ARC_MOCK_RESI_SINGLE_ELEC_SINGLE_GAS_SINGLE_WATER_SINGLE_METERS | One 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.
Password | Result | Credential status / statusDetail |
---|---|---|
VERIFIED | The credential was verified within the Connect RTCV timeout | CONNECTION_SUCCESS / LOGIN_AND_DATA_DISCOVERY_SUCCESSFUL |
REJECTED | The credential was rejected within the Connect RTCV timeout | CONNECTION_FAILURE / INVALID_CREDENTIALS |
TIMEOUT_VERIFIED | The credential was verified after the Connect timeout | CONNECTION_SUCCESS / LOGIN_AND_DATA_DISCOVERY_SUCCESSFUL |
TIMEOUT_REJECTED | The credential was rejected after the Connect timeout | CONNECTION_FAILURE / INVALID_CREDENTIALS |
TEMPORARY_ERROR | An error occurred (like the provider website was down) but Arc will automatically retry | CONNECTION_IN_PROGRESS / PROVIDER_WEBSITE_INACCESSIBLE |
FATAL_ERROR_ACCOUNT_BLOCKED | We 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_ERROR | General error state reached before the Connect timeout was hit. | CONNECTION_IN_PROGRESS /ISSUE_UNDER_REVIEW |
FATAL_ERROR_TIMEOUT | General 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 anaccountNumber
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 Number | Mock Data Scenario |
---|---|
11235813010 | One electric account with one meter |
11235813020 | One electric account with three meters |
11235813030 | One gas account with one meter |
11235813040 | One gas account with three meters |
11235813050 | One combined electric and gas account with one electric meter and one gas mete |
11235813060 | One 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"
}
Updated 8 months ago