Skip to main content
The FHIR simulator is a fully functional FHIR R4 server backed by Google Cloud Healthcare API. It stands in for an EHR like Epic, Cerner, or Athena. Your agent authenticates with SMART on FHIR client credentials, reads and writes resources (Patient, Condition, MedicationRequest, Encounter, Observation, Appointment, DiagnosticReport, AllergyIntolerance, Procedure, and more), and the verification engine reads the final store to score fhir-resource-state criteria.

​
How your agent connects

When a benchmark run is created, the response includes the FHIR sandbox’s base URL under endpoints.fhir (or equivalent). All FHIR traffic is proxied through /v1/benchmark-runs/{benchmark_run_id}/fhir/* and authenticated with the run-scoped bearer token. During playground authoring, the sandbox also exposes direct endpoints at /services/{service_id}/fhir/* for local testing. Under the hood the sandbox is a dedicated FHIR store (one per playground) seeded with the linked dataset’s patients, conditions, medications, encounters, and related resources.

​
Endpoints

MethodEndpointDescription
ALL/v1/benchmark-runs/{id}/fhir/*Transparent proxy to the sandbox FHIR store (search, read, create, update, transaction bundles). Authenticated by the run-scoped bearer token.
The v1 proxy handles authentication for you, so you do not need to fetch a separate SMART token to call FHIR endpoints during a benchmark run. During playground authoring, the direct service at /services/{service_id}/fhir/* also exposes SMART on FHIR discovery and token issuance at /services/{service_id}/fhir/.well-known/smart-configuration and /services/{service_id}/fhir/token. See the SMART configuration and FHIR token reference pages.

​
Driving the rollout

Use the proxied FHIR endpoints with the run token. Search for a patient: 
curl "https://api.verial.ai/v1/benchmark-runs/$BENCHMARK_RUN_ID/fhir/Patient?identifier=BCB123456789" \
  -H "Authorization: Bearer $RUN_TOKEN"
Create an appointment: 
curl -X POST "https://api.verial.ai/v1/benchmark-runs/$BENCHMARK_RUN_ID/fhir/Appointment" \
  -H "Authorization: Bearer $RUN_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Appointment",
    "status": "booked",
    "participant": [
      { "actor": { "reference": "Patient/john-smith" }, "status": "accepted" },
      { "actor": { "display": "Dr. Rivera" }, "status": "accepted" }
    ]
  }'

​
Configuration

The FHIR simulator accepts minimal configuration at create time. The interesting shape of the simulator comes from the FHIR dataset linked to it, which defines the patients, encounters, and clinical history that get seeded into the store. 
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"}'
To seed the simulator with realistic clinical data, create a FHIR dataset and link it via the sandbox: POST /sandboxes/{id}/datasets/{dataset_id}.

​
Verification

The fhir-resource-state check reads the FHIR store after the rollout and asserts that a search returns resources with expected field values. See the Criteria concept page for the full spec. 
{
  "label": "Follow-up appointment booked with Dr. Rivera",
  "weight": 1.0,
  "axis": "correctness",
  "assertion": {
    "assert": "fhir-resource-state",
    "resource_type": "Appointment",
    "search": { "patient": "Patient/john-smith", "status": "booked" },
    "fields": [
      { "path": "participant.0.actor.display", "expected": "Dr. Rivera" }
    ]
  }
}

​
Next Steps

Criteria

The full list of typed assertions the verification engine supports.

Simulators overview

How simulators compose into environments and provision into sandboxes.

FHIR API reference

SMART configuration, token issuance, and FHIR request shapes.

Datasets

Seed realistic patient data into the FHIR store.