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

# HL7

> HL7v2 messaging for ADT, ORU, ORM, and SIU feeds.

The HL7 simulator accepts and produces HL7 v2 messages, the legacy messaging standard that still powers most hospital interfaces for patient movement, lab results, orders, and scheduling. Your agent reads inbound HL7 messages out of a sandbox inbox and writes outbound messages back, and the verification engine scores the outbound traffic with `hl7-structural` criteria.

## How your agent connects

The HL7 sandbox exposes a message inbox (pre-seeded with any messages the task scenario set up) and an outbound endpoint for messages your agent emits. Both are reached via HTTP under the benchmark-run path and authenticated with the run-scoped bearer token. The payload is the raw HL7v2 pipe-delimited message as a string.

Supported message types:

* **ADT** (Admit/Discharge/Transfer) for patient movement
* **ORU** (Observation Result) for lab results
* **ORM** (Order Message) for orders
* **SIU** (Scheduling Information Unsolicited) for appointment scheduling

## Endpoints

| Method | Endpoint                               | Description                                           |
| ------ | -------------------------------------- | ----------------------------------------------------- |
| `GET`  | `/v1/benchmark-runs/{id}/hl7/inbox`    | Read inbound HL7 messages seeded by the task scenario |
| `POST` | `/v1/benchmark-runs/{id}/hl7/outbound` | Submit an outbound HL7 message; returns an HL7 ACK    |

During authoring, the same semantics are exposed at `/services/{service_id}/hl7/messages` (see [Send HL7 message](/api-reference/hl7/send)).

## Driving the rollout

Fetch the inbox:

```bash theme={null}
curl "https://api.verial.ai/v1/benchmark-runs/$BENCHMARK_RUN_ID/hl7/inbox" \
  -H "Authorization: Bearer $RUN_TOKEN"
```

Send an ADT^A01 admission message:

```bash theme={null}
curl -X POST "https://api.verial.ai/v1/benchmark-runs/$BENCHMARK_RUN_ID/hl7/outbound" \
  -H "Authorization: Bearer $RUN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload": "MSH|^~\\&|VERIAL|AGENT|EHR|FACILITY|20260423||ADT^A01|12345|P|2.5\rPID|1||12345^^^MRN||Smith^John||19650315|M\rPV1|1|I|ICU^101^A"}'
```

The response contains an HL7 ACK (`MSA|AA|12345`) when the message is accepted. Rejected messages return `MSA|AE` or `MSA|AR` with a reason.

## Configuration

The HL7 simulator has no required configuration at create time. Inbound traffic is driven by the dataset or by task scenarios that seed messages into the inbox before a task run starts.

```bash theme={null}
curl -X POST https://api.verial.ai/simulators \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "Hl7", "name": "Lab Feed"}'
```

## Verification

The `hl7-structural` check parses each outbound HL7 message, correlates by MSH fields or trigger event, and asserts on segment values by path.

```json theme={null}
{
  "label": "ADT^A01 admission message sent for correct patient",
  "weight": 1.0,
  "assertion": {
    "assert": "hl7-structural",
    "correlate_by": { "MSH.9.1": "ADT", "MSH.9.2": "A01" },
    "fields": [
      { "path": "PID.5.1", "expected": "Smith" },
      { "path": "PV1.2", "expected": "I" }
    ]
  }
}
```

See the [Criteria concept page](/guides/concepts/criteria#hl7-adt-sent) for more examples and the full assertion spec.

## Next Steps

<CardGroup cols={2}>
  <Card title="FHIR" icon="database" href="/guides/simulators/fhir">
    Pair HL7 ADT flows with a FHIR EHR for end-to-end admission testing.
  </Card>

  <Card title="Criteria" icon="check-double" href="/guides/concepts/criteria">
    Full reference for `hl7-structural` assertions.
  </Card>

  <Card title="HL7 API reference" icon="code" href="/api-reference/hl7/send">
    Direct-access HL7 send endpoint for authoring.
  </Card>

  <Card title="Simulators overview" icon="server" href="/guides/simulators/overview">
    Lifecycle, provisioning, and configuration patterns.
  </Card>
</CardGroup>