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

# FHIR

> A fully functional FHIR R4 EHR backed by GCP Healthcare API, with SMART on FHIR auth.

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

| Method | Endpoint                         | Description                                                                                                                                    |
| ------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `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](/api-reference/fhir/smart-config) and [FHIR token](/api-reference/fhir/token) reference pages.

## Driving the rollout

Use the proxied FHIR endpoints with the run token.

Search for a patient:

```bash theme={null}
curl "https://api.verial.ai/v1/benchmark-runs/$BENCHMARK_RUN_ID/fhir/Patient?identifier=BCB123456789" \
  -H "Authorization: Bearer $RUN_TOKEN"
```

Create an appointment:

```bash theme={null}
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](/guides/concepts/datasets) linked to it, which defines the patients, encounters, and clinical history that get seeded into the store.

```bash theme={null}
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](/guides/concepts/datasets) 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](/guides/concepts/criteria#fhir-appointment-booked) for the full spec.

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Criteria" icon="check-double" href="/guides/concepts/criteria">
    The full list of typed assertions the verification engine supports.
  </Card>

  <Card title="Simulators overview" icon="server" href="/guides/simulators/overview">
    How simulators compose into environments and provision into sandboxes.
  </Card>

  <Card title="FHIR API reference" icon="code" href="/api-reference/fhir/smart-config">
    SMART configuration, token issuance, and FHIR request shapes.
  </Card>

  <Card title="Datasets" icon="database" href="/guides/concepts/datasets">
    Seed realistic patient data into the FHIR store.
  </Card>
</CardGroup>