Sandboxes - Verial

Sandboxes are running instances of a Simulator. Each sandbox provides live credentials (FHIR endpoints, phone numbers, fax numbers, SFTP paths, portal URLs) and records all interactions as events. Sandboxes can be created standalone or as part of a Playground. After a task rollout, sandbox state is the input the verification engine scores against.

Endpoints

Method	Endpoint	Description
`GET`	`/sandboxes`	List sandboxes
`POST`	`/sandboxes`	Create a sandbox
`GET`	`/sandboxes/{id}`	Get sandbox details
`GET`	`/sandboxes/{id}/events`	List sandbox events
`POST`	`/sandboxes/{id}/teardown`	Tear down a sandbox
`POST`	`/sandboxes/{id}/datasets/{datasetId}`	Add a dataset to the sandbox
`DELETE`	`/sandboxes/{id}/datasets/{datasetId}`	Remove a dataset from the sandbox

Sandbox Object

Field	Type	Description
`id`	string	Unique identifier
`simulator_id`	string	Source Simulator
`playground_id`	string \| null	Parent Playground, if part of one
`status`	string	Current status (provisioning, active, teardown, etc.)
`credentials`	object \| null	Protocol-specific access credentials. See Credentials by Simulator Type.
`organization_id`	string	Parent organization
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last modification timestamp

Credentials by Simulator Type

The credentials object is shaped by the source simulator’s type. Typical shapes:

Payer (Web Simulator)

Returned when the simulator’s config.portal is set (see the Web Portal catalog).

Field	Type	Description
`portal_url`	string	URL for a browser agent to navigate to (e.g. `https://radmd.sim.verial.ai`)
`username`	string	Auto-generated login username, scoped to this sandbox
`password`	string	Auto-generated login password, scoped to this sandbox
`api_url`	string	REST base URL for the backing payer endpoints (`/prior-auths`, `/patients`, `/providers`)

{
  "portal_url": "https://radmd.sim.verial.ai",
  "username": "provider_a1b2c3",
  "password": "Kq7!mZxP9vRnT2wL",
  "api_url": "https://api.verial.ai/sandboxes/sbx_01H.../web-sim/payer"
}

FHIR

Field	Type	Description
`fhir_base_url`	string	FHIR R4 base URL
`token_url`	string	SMART on FHIR token endpoint
`client_id`	string	OAuth2 client ID
`client_secret`	string	OAuth2 client secret

Voice

Field	Type	Description
`phone_number`	string	E.164 number to call

HL7

Field	Type	Description
`inbox_url`	string	URL to GET inbound messages
`outbound_url`	string	URL to POST outbound messages

Other simulator types follow the same pattern: connection details needed to read from and write to the live instance.

SDK Example

// Create a standalone sandbox
const sandbox = await verial.sandboxes.create({
  simulatorId: 'sim_abc123',
})

// List sandboxes (optionally filter by playground)
const sandboxes = await verial.sandboxes.list({ playgroundId: 'pg_abc123' })

// Get sandbox details (includes credentials)
const details = await verial.sandboxes.get({ id: sandbox.id })

// List interaction events
const events = await verial.sandboxes.listEvents({ id: sandbox.id })

// Load a dataset
await verial.sandboxes.addDataset({
  sandboxId: sandbox.id,
  datasetId: 'ds_abc123',
})

// Remove a dataset
await verial.sandboxes.removeDataset({
  sandboxId: sandbox.id,
  datasetId: 'ds_abc123',
})

// Tear down when done
await verial.sandboxes.teardown({ id: sandbox.id })

​Endpoints

​Sandbox Object

​Credentials by Simulator Type

​Payer (Web Simulator)

​FHIR

​Voice

​HL7

​SDK Example