Skip to main content
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

MethodEndpointDescription
GET/v1/benchmark-runs/{id}/hl7/inboxRead inbound HL7 messages seeded by the task scenario
POST/v1/benchmark-runs/{id}/hl7/outboundSubmit 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).

​
Driving the rollout

Fetch the inbox: 
curl "https://api.verial.ai/v1/benchmark-runs/$BENCHMARK_RUN_ID/hl7/inbox" \
  -H "Authorization: Bearer $RUN_TOKEN"
Send an ADT^A01 admission message: 
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. 
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. 
{
  "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 for more examples and the full assertion spec.

​
Next Steps

FHIR

Pair HL7 ADT flows with a FHIR EHR for end-to-end admission testing.

Criteria

Full reference for hl7-structural assertions.

HL7 API reference

Direct-access HL7 send endpoint for authoring.

Simulators overview

Lifecycle, provisioning, and configuration patterns.