👍

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)

*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.

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 Multi-Factor Authentication

Some utility websites require multi-factor authentication to login to the website and access bills. You can simulate this workflow by using the MFA_REQUIRED password for any of the sandbox scenario usernames above. The overall flow will be that you are prompted for the verification method (e.g. e-mail or text), and then prompted for the one-time passcode. For the sandbox environment, the only valid one-time passcode is 12345, but you can test the incorrect passcode scenario with any other value.

Example: Multi-Factor Authentication

Initial request:

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": "MFA_REQUIRED",
         "interactive": true,
         "correlationId": "sandbox_test"
      }'

Response:

{
  "correlationId" : null,
  "createdAt" : "2024-09-17T17:30:40.000+00:00", 
  "createdBy" : "connect2_internal_user",
  "id" : "crd_6e60787c-ed56-4336-b52d-01a6e3ac0aae",
  "isActive" : true,
  "isCustomerActionRequired" : false,
  "isThirdPartyPortal" : false,
  "lastModifiedAt" : "2024-09-17T17:30:41.000+00:00",
  "lastModifiedBy" : "connect2_internal_user",
  "nextScheduledAccountRunAt" : "2024-09-17T17:30:40.000+00:00",
  "provider": {
    "country": null,
    "id": "prv_d06d8bc9-495b-4ba6-b281-b40934cd898e",
    "providerName": "Arc Municipal Service",
    "supportsCredentialValidation": true,
    "website": ""
  },
  "status" : "CONNECTION_IN_PROGRESS",
  "statusDetail" : "DATA_EXTRACTION_IN_PROGRESS",
  "totalAccounts" : 0,
  "username" : "ARC_MOCK_RESI_MULTI_ELEC_SINGLE_METER",
  "username2" : null,
  "username3" : null,
  "username4" : null,
  "website" : null
},

Webhook prompting for the verification method; the available options will be present in data.verificationMethods resource:

{
  "createdAt" : "2024-09-17T17:30:44.641+00:00",
  "data" : {
    "credential" : {
      "correlationId" : null,
      "createdAt" : "2024-09-17T17:30:40.000+00:00",
      "createdBy" : "connect2_internal_user",
      "id" : "crd_6e60787c-ed56-4336-b52d-01a6e3ac0aae",
      "isActive" : true,
      "isCustomerActionRequired" : false,
      "isThirdPartyPortal" : false,
      "lastModifiedAt" : "2024-09-17T17:30:41.000+00:00",
      "lastModifiedBy" : "connect2_internal_user",
      "nextScheduledAccountRunAt" : "2024-09-17T17:30:40.000+00:00",
      "provider": {
        "country": null,
        "id": "prv_d06d8bc9-495b-4ba6-b281-b40934cd898e",
        "providerName": "Arc Municipal Service",
        "supportsCredentialValidation": true,
        "website": ""
      },
      "status" : "CONNECTION_IN_PROGRESS",
      "statusDetail" : "DATA_EXTRACTION_IN_PROGRESS",
      "totalAccounts" : 0,
      "username" : "ARC_MOCK_RESI_MULTI_ELEC_SINGLE_METER",
      "username2" : null,
      "username3" : null,
      "username4" : null,
      "website" : null
    },
    "verificationMethods" : [ {
      "identifier" : "********@gmail.com",
      "isResubmission" : false,
      "name" : "********@gmail.com",
      "type" : "email"
    }, {
      "identifier" : "***-***-1234",
      "isResubmission" : false,
      "name" : "***-***-1234",
      "type" : "text"
    } ]
  },
  "errors" : [ ],
  "eventType" : "MFA_CHALLENGE_METHOD",
  "id" : "whk_1ef751a9-1bc4-d98e-b095-d2dcd397a413",
  "resource" : "MFA_METHOD_PROMPT"
}

Response to select verification method:

curl -X PUT \
	--url "https://sandbox.api.arcadia.com/credentials/crd_6e60787c-ed56-4336-b52d-01a6e3ac0aae/mfaMethod"
	-H "Authorization: Bearer <your_token_here>"
	-H "Arc-Version: 2024-02-21"
	-H "Content-type: application/json"
	-d '{
        "name": "***-***-1234",
        "type": "text"
      }'

Webhook prompting for the one-time passcode:

{
  "createdAt" : "2024-09-17T17:30:59.146+00:00",
  "data" : {
    "credential" : {
      "correlationId" : null,
      "createdAt" : "2024-09-17T17:30:40.000+00:00",
      "createdBy" : "connect2_internal_user",
      "id" : "crd_1ef751a8-ed50-d89d-bb75-e2aa759597b0",
      "isActive" : false,
      "isCustomerActionRequired" : false,
      "isThirdPartyPortal" : false,
      "lastModifiedAt" : "2024-09-17T17:30:41.000+00:00",
      "lastModifiedBy" : "connect2_internal_user",
      "nextScheduledAccountRunAt" : "2024-09-17T17:30:40.000+00:00",
      "provider": {
        "country": null,
        "id": "prv_d06d8bc9-495b-4ba6-b281-b40934cd898e",
        "providerName": "Arc Municipal Service",
        "supportsCredentialValidation": true,
        "website": ""
      },
      "status" : "CONNECTION_IN_PROGRESS",
      "statusDetail" : "DATA_EXTRACTION_IN_PROGRESS",
      "totalAccounts" : 0,
      "username" : "ARC_MOCK_RESI_MULTI_ELEC_SINGLE_METER",
      "username2" : null,
      "username3" : null,
      "username4" : null,
      "website" : null
    },
    "isResubmission" : false,
    "selectedVerificationMethod" : {
      "identifier" : "1",
      "isResubmission" : false,
      "name" : "***-***-1234",
      "type" : "other"
    }
  },
  "errors" : [ ],
  "eventType" : "MFA_CHALLENGE_CODE",
  "id" : "whk_1ef751a9-a619-d333-b095-d2dcd397a413",
  "resource" : "MFA_CODE_PROMPT"
}

Response to enter one-time passcode:

curl -X PUT \
	--url "https://sandbox.api.arcadia.com/credentials/crd_6e60787c-ed56-4336-b52d-01a6e3ac0aae/oneTimePass?oneTimePass=12345"
	-H "Authorization: Bearer <your_token_here>"
	-H "Arc-Version: 2024-02-21"

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

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"
}