> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verial.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Simulators
> Simulated healthcare interfaces your agent connects to.
A simulator is a reusable definition of a simulated healthcare interface. Each simulator speaks one protocol (FHIR, HL7v2, X12, voice, fax, web portal, SFTP, messaging, CDS Hooks) and composes into an [environment](/guides/concepts/environments) alongside other simulators. When a [playground](/guides/concepts/playgrounds) is created or a [benchmark run](/guides/concepts/runs) starts, every linked simulator is provisioned as a live **sandbox** with real credentials. Your agent drives those sandboxes during the rollout, and the [verification engine](/guides/concepts/verification) reads the final sandbox state to score [criteria](/guides/concepts/criteria).
## Protocol matrix
| Simulator | Protocol | Production equivalent | Agent connects via | Verification check |
| --------------------------------------------- | ----------------------------- | ----------------------------------------- | ------------------------------------------------------- | -------------------------- |
| [FHIR](/guides/simulators/fhir) | REST (FHIR R4) | Epic, Cerner, Athena EHR | `/v1/benchmark-runs/{id}/fhir/*` with SMART token | `fhir-resource-state` |
| [HL7](/guides/simulators/hl7) | HL7v2 | Lab and ADT feeds | `/v1/benchmark-runs/{id}/hl7/inbox` and `/hl7/outbound` | `hl7-structural` |
| [X12](/guides/simulators/x12) | X12 EDI (270/271/276/277/278) | Change Healthcare, Availity clearinghouse | Clearinghouse endpoints on the sandbox | `x12-response` |
| [Voice](/guides/simulators/voice) | Phone / IVR | Member services phone line | Leased phone number | `voice-transcript` |
| [Fax](/guides/simulators/fax) | Fax (PDF/TIFF) | Referral intake, prior auth cover sheets | Fax number on the sandbox, `POST /faxes` | Interaction evidence (OCR) |
| [Web Portal](/guides/simulators/web-portal) | HTTPS UI + REST | RadMD, CoverMyMeds | Portal URL + username/password, `api_url` | `portal-state-match` |
| [Files (SFTP)](/guides/simulators/files-sftp) | SFTP (files API) | Payer SFTP drop, claims batch | `/v1/benchmark-runs/{id}/files/*` | `sftp-file-present` |
| [Messages](/guides/simulators/messages) | REST (SMS / chat) | Appointment reminders, patient outreach | `/messages` REST endpoints | Interaction evidence |
| [CDS Hooks](/guides/simulators/cds-hooks) | REST (CDS Hooks 1.1) | EHR decision support surfaces | `/cds/*` endpoints on the sandbox | Interaction evidence |
Each row's verification check is documented alongside its peers on the [Criteria](/guides/concepts/criteria) page.
## Lifecycle
```mermaid theme={null}
graph LR
S["Simulator
(created)"]:::state --> L["Linked to
Environment"]:::state
L --> B["Sandbox
(provisioned on run)"]:::state
B --> A["Agent drives
rollout"]:::state
A --> T["Torn down
(evidence retained)"]:::state
classDef state fill:#2563eb,color:#fff,stroke:#1d4ed8
```
1. **Create** the simulator once, configure it (e.g. portal flavor, IVR flow, determination rules).
2. **Link** it to one or more environments. Environments compose simulators plus [datasets](/guides/concepts/datasets).
3. **Provision** a sandbox when a playground is created or a benchmark run starts. The sandbox gets its own credentials, isolated state, and evidence stream.
4. **Drive** the sandbox from your agent using the `/v1/benchmark-runs/{id}/` endpoints (or the direct sandbox endpoints during authoring).
5. **Tear down** at the end of the run. The sandbox stops accepting traffic, but all recorded [interactions](/guides/concepts/interactions) remain for review and verification.
## Creating and linking
Simulators are standalone resources that you link to environments. Configuration is set at create time and can be updated until the simulator is provisioned:
```bash theme={null}
# Create the FHIR simulator
curl -X POST https://api.verial.ai/simulators \
-H "Authorization: Bearer $VERIAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "Fhir", "name": "Primary EHR"}'
# → save the returned id as $FHIR_SIMULATOR_ID
# Create the payer portal simulator
curl -X POST https://api.verial.ai/simulators \
-H "Authorization: Bearer $VERIAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "Payer",
"name": "RadMD Sandbox",
"config": {
"portal": "radmd",
"default_determination": { "status": "approved" }
}
}'
# → save the returned id as $PORTAL_SIMULATOR_ID
# Create the environment (environments are also available via the SDK as verial.environments.create)
curl -X POST https://api.verial.ai/environments \
-H "Authorization: Bearer $VERIAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Regional Medical Center"}'
# → save the returned id as $ENVIRONMENT_ID
# Link the simulators to the environment
curl -X POST "https://api.verial.ai/environments/$ENVIRONMENT_ID/simulators/$FHIR_SIMULATOR_ID" \
-H "Authorization: Bearer $VERIAL_API_KEY"
curl -X POST "https://api.verial.ai/environments/$ENVIRONMENT_ID/simulators/$PORTAL_SIMULATOR_ID" \
-H "Authorization: Bearer $VERIAL_API_KEY"
```
See the [Simulators API reference](/api-reference/resources/simulators) for the full list of supported types and config fields.
## Provisioning
When a playground or benchmark run starts, Verial walks the environment's simulator list and provisions each one:
* **Allocate resources.** FHIR stores are created in GCP Healthcare, phone numbers are leased from the voice pool, SFTP drops are initialized, portal logins are minted, CDS Hooks endpoints are registered.
* **Load datasets.** Any datasets linked to the simulator are seeded into the fresh sandbox (patients into FHIR, files into SFTP, determination rules into the portal).
* **Return credentials.** The benchmark-run response includes a `endpoints` map (for path-routed simulators) and, where applicable, each sandbox's `credentials` payload (phone numbers, portal URLs, usernames, fax numbers).
* **Record interactions.** Every request to the sandbox is captured as evidence. Voice calls produce transcripts, fax submissions produce OCR'd documents, portal submissions produce UI events.
* **Tear down.** After the last task run completes, sandboxes release their resources. Interaction evidence persists so criteria can score the rollout.
See [Sandboxes](/guides/concepts/sandboxes) for branching, checkpoints, and direct-access semantics.
## Configuration vs runtime credentials
Simulator configuration and runtime credentials are distinct.
* **Configuration** is set at `POST /simulators` time (and editable via `PATCH /simulators/{id}` until provisioning). It describes the shape of the simulated system: which payer portal to render, which IVR menus to expose, which determination rules to apply, which CDS cards to return.
* **Runtime credentials** are generated when the sandbox is provisioned. They are unique per sandbox, scoped to that sandbox's lifetime, and include things like a FHIR base URL, a leased phone number, a portal username and password, a fax number, or an SFTP root path. The agent reads them out of the benchmark-run response or the sandbox's `credentials` payload.
This split means you can reuse the same simulator definition across many runs. Each run gets its own isolated sandbox without leaking state or credentials between rollouts.
## Next Steps
Provision a FHIR R4 EHR and drive it with SMART on FHIR.
Simulated RadMD and CoverMyMeds payer portals.
Phone / IVR lines with recorded transcripts.
The typed assertions the verification engine runs against sandbox state.