Developers · Interoperability
HL7 v2 interfaces
Lab results, radiology reports, and hospital admit, discharge and demographic messages, sent to one practice over HTTPS by a lab, an imaging center, a hospital or an interface engine. ChartVoyant answers every authenticated, well-formed message with an HL7 acknowledgment, files matched results to the chart for a clinician to review, and never creates or merges a patient.
POSThttps://chartvoyant.com/api/v1/interop/hl7/{interfaceId}docs below
At a glance
| Status | Deployed in production on October 29, 2026. Each interface is turned on individually, for one practice, once its onboarding is complete: agreements, a synthetic test run, independent security testing and the practice's go-ahead. |
| Endpoint | POST https://chartvoyant.com/api/v1/interop/hl7/{interfaceId}, one message per request. ChartVoyant assigns the interface ID when it sets up your feed. |
| Standard | HL7 v2 in the pipe-delimited ER7 encoding. Version 2.5.1, or 2.3 through 2.5.1 on an interface set up with the tolerant profile. |
| Transport | HTTPS, HL7 over HTTP style: the request body is the raw message, sent as x-application/hl7-v2+er7 or application/hl7-v2, and the ACK comes back in the response body. MLLP and SFTP are not available. |
| Authentication | An HL7 sender key that can deliver to one interface and do nothing else, or a SMART Backend Services token that carries system/hl7v2-ingest. See Authentication. |
| Messages | ORU^R01 for lab and radiology results; ADT^A01, A03, A04, A08, A11, A13, A28 and A31 for hospital events and demographics. An A40 merge becomes a notice for staff and never merges charts. |
| Limits | 2 MiB per message. 20 messages per second and 600 per minute for each interface. |
| Where data lands | One practice per interface. A result files only to a patient matched with certainty, and is marked not yet reviewed until a clinician reviews it. |
How an interface goes live
The receive endpoint, result filing, the review desk and hospital event notices run in production. Each interface carries its own approvals before it takes a message: an interface agreement, a business associate agreement (and one for any intermediary in the path), the message types it may send, independent security testing that covers this endpoint, and the practice's go-ahead. Testing runs first on a separate interface in a ChartVoyant sandbox office, with processing ID T and synthetic messages, and it needs the same approvals on file.
Send a message
Synthetic values throughout. Use carriage returns between segments; line feeds are accepted too, and the strict profile notes them with a warning. Use the MSH-3 to MSH-6 values and the processing ID agreed when your interface is set up.
Request
POST https://chartvoyant.com/api/v1/interop/hl7/INTERFACE_ID Authorization: Bearer cvk_YOUR_HL7_SENDER_KEY Content-Type: x-application/hl7-v2+er7 MSH|^~\&|SYNLAB|SYNLAB-CLEVELAND|CHARTVOYANT|EXAMPLE-PRACTICE|20261031101500-0400||ORU^R01^ORU_R01|SYN000123|T|2.5.1 PID|1||SYN-000123^^^SYNLAB^MR||ZZTEST^ALPHA||19700101|F ORC|RE|PLACER_ORDER_ID|SYN-F-7781 OBR|1|PLACER_ORDER_ID|SYN-F-7781|4548-4^Hemoglobin A1c/Hemoglobin.total in Blood^LN|||20261030083000-0400|||||||||||||||20261031101000-0400||CH|F OBX|1|NM|4548-4^Hemoglobin A1c/Hemoglobin.total in Blood^LN||6.1|%|4.0-5.6|H|||F
Response
HTTP/1.1 200 OK Content-Type: x-application/hl7-v2+er7 MSH|^~\&|CHARTVOYANT|EXAMPLE-PRACTICE|SYNLAB|SYNLAB-CLEVELAND|20261031141501+0000||ACK^R01^ACK|ACK_CONTROL_ID|T|2.5.1 MSA|AA|SYN000123
The ACK swaps your sending and receiving application and facility, echoes your MSH-10 in MSA-2 and your MSH-11 and MSH-12, and stamps its own time in UTC. Error ACKs add ERR segments with an HL7 table 0357 code and a position, never a field value, so an ACK holds no patient data.
Acknowledgments
AA means the message is stored durably. Filing runs after the ACK, so a busy chart never holds your connection. ChartVoyant never sends AA and later a negative ACK: anything that cannot be filed after AA goes to a person at the practice, and you are not asked to resend.
| Answer | When | What to do |
|---|---|---|
| HTTP 401 | No credential, an invalid one, an unknown interface, or a credential that is not the one bound to that interface. All four look the same. No ACK; nothing stored. | Check the key or token and the interface ID. |
| HTTP 400 | A malformed request: another content type, an empty body, or an interface ID that is not a UUID. No ACK; nothing stored. | Fix the request. |
| HTTP 413 | The body is over 2 MiB. No ACK; nothing stored. | Send smaller messages. |
| 200, MSA AA | Stored. An exact resend (same MSH-10, same bytes) gets the original answer and is not stored twice. | Nothing. |
| 200, MSA AE | Stored, but not usable as sent: required content is missing (101), the same MSH-10 came back with different content (205), an ADT carried more than one PID, or one patient group in a multi-patient ORU failed, with an ERR at the failing segment in that group. | Correct it and resend under a new MSH-10. The practice sees it too. |
| 200, MSA AE, 207 | Not accepted, with the generic text "Message could not be accepted": the interface is not turned on or is paused, an approval is missing or lapsed, the processing ID does not match, the rate limit was reached, or a temporary fault. After some temporary faults a copy is held for review. The text is the same for all of them on purpose. | Back off and resend the same message. If it continues, contact us. |
| 200, MSA AR | Not processed: an unsupported message type or event (200, 201), an unsupported version (203), or MSH-3 to MSH-6 that do not match the interface (204). | Do not resend it as is. |
The generic answer
MSH|^~\&|CHARTVOYANT|EXAMPLE-PRACTICE|SYNLAB|SYNLAB-CLEVELAND|20261031141501+0000||ACK^R01^ACK|ACK_CONTROL_ID|T|2.5.1 MSA|AE|SYN000124 ERR|||207^Application internal error^HL70357|E||||Message could not be accepted
Enhanced mode. When MSH-15 or MSH-16 is filled in, the same points answer CA, CE or CR. Application-level acknowledgments are not sent.
Message types
Each interface lists the types it may send. Anything else is refused with AR.
| Message | Use | What ChartVoyant does |
|---|---|---|
| ORU^R01 | Lab results | Files a diagnostic report and its observations for the matched patient, marked not yet reviewed, and opens one inbox item for the ordering clinician. |
| ORU^R01 | Radiology and other narrative reports | Files the report text as a radiology report, stores an embedded PDF when one is sent, and opens an inbox item. |
| ADT^A01, A04, A03 | Admit, register, discharge | Records a hospital event, separate from the practice's own visits, with an inbox notice. A discharge notice is high priority so the practice can follow up. |
| ADT^A08, A28, A31 | Demographic updates | Writes a proposal. Nothing on the chart changes until staff accept it field by field. |
| ADT^A11, A13 | Cancel admit, cancel discharge | Marks the earlier event cancelled. Nothing is deleted. |
| ADT^A40 | Merge | Becomes a notice for staff. Charts are never merged from a message. |
| ORM, MDM, VXU and others | Not supported | Refused with AR and ERR 200 or 201. |
One ORU can carry results for several patients. Each PID and the segments after it are matched and filed on their own. A group that fails goes to review without stopping the others, and the ACK is AE with an ERR at the failing segment in that group. An ADT carries one patient: a second PID makes the whole message AE.
After the ACK
- Matching is strict. A result files on its own only when PID-3 carries an identifier the practice has already confirmed for your feed and the birth date agrees, or when your placer order number (ORC-2 or OBR-2) is a ChartVoyant order whose patient has the same birth date and family name. Anything less goes to a review queue with the evidence. PID-19 is ignored.
- Never a new patient, never a merge. An unmatched message writes nothing to any chart. Staff pick the patient, or mark the message not theirs.
- The lab's flags stay the lab's. OBX-8 is shown as sent. When it is empty, no flag is made up from the reference range. Routing and priority come from your flags and the order.
- Corrections are tracked. A corrected result (
Cin OBR-25 or OBX-11) keeps the earlier version, opens a new high-priority inbox item and clears the earlier review.DorWmarks a result as removed by the lab. An older preliminary that arrives after a final is kept as history and not applied. - Attachments. An embedded PDF (OBX-2
ED) is stored with the report. A reference pointer (RP) is never fetched. - Patients see results on the practice's usual schedule. Review does not delay the patient portal. A clinician can hold one result at a time under 45 CFR 171.201, with the reason recorded.
- No AI on results in production. A descriptive summary beside the lab's values exists for test environments only. The lab's values are never changed.
- Every message is kept. The raw message is archived, encrypted, for ten years. Staff can replay a message that failed, and a replay never files a result twice.
Authentication
One credential per interface, bound to it when the interface is set up. A staff sign-in and a self-serve sandbox key are never accepted.
| Credential | How it works |
|---|---|
| HL7 sender key | Authorization: Bearer cvk_…. ChartVoyant issues it with a single permission: delivering HL7 to the interface it is bound to. It cannot read or write anything else, and ordinary read-only and full-access API keys cannot deliver HL7. |
| SMART Backend Services | Get a token from https://auth.chartvoyant.com/oauth/token with client_credentials, a private_key_jwt assertion signed RS384 or ES384, and scope=system/hl7v2-ingest. The scope is granted only to a backend client registered for it at that practice. system/*.rs does not include it, discovery does not list it, and a token that carries only this scope reads no FHIR data. See SMART Backend Services. |
| Request signing | An extra HMAC check (X-CV-Timestamp and X-CV-Signature: hex HMAC-SHA256 over the timestamp, a newline and the hex SHA-256 of the body, within five minutes) is defined but not offered yet. Do not send those headers: until a signing secret is set up for your interface, a request that carries them is refused with 401. |
| Mutual TLS | Not available. |
Limits
| Limit | Value |
|---|---|
| Message size | 2 MiB per request body. Larger is HTTP 413. |
| Rate, per interface | 20 messages per second and 600 per minute. Past that, the answer is the generic AE and nothing is stored, so slow down and resend. |
| Messages per request | One. Batch envelopes (FHS and BHS) are not supported. |
| Profiles | Strict: v2.5.1 and UTF-8, with a warning for segment endings other than a carriage return. Tolerant: v2.3, 2.3.1, 2.4, 2.5 and 2.5.1, Latin-1 text, and embedded PDFs split across repetitions or segments. Both keep unknown Z-segments. |
How to get connected
- Tell us about the feed
Email info@chartvoyant.com with the practice, who is sending, the message types and HL7 version, your MSH-3 and MSH-4, the assigning authority in PID-3, the expected volume, any intermediary in the path, and a technical contact. Send no patient data.
- Sign the agreements
The HL7 v2 Interface Agreement, signed online at e-sign.chartvoyant.com: one interface, one practice, a twelve-month term, covering transport and security, testing first, breach notice, contacts, termination and the treatment purpose. A business associate agreement is separate. An interface engine, HIE or VPN provider in the path needs its own.
- We set up the interface
For that one practice: your credential is bound to it, and the expected MSH values, processing ID and message types are recorded. The interface ID and credential go to your technical contact, never into a ticket or a chat.
- Test with synthetic messages
Testing runs on a separate interface in a ChartVoyant sandbox office, with processing ID
Tand synthetic patients only. It needs the same approvals on file, including independent security testing and the practice's go-ahead. Work through the acknowledgment table until every message type you send answersAA. - Go live
The practice's own interface is turned on for real patient data once every approval is on file and the practice says go. If an approval lapses or the interface changes, the feed stops until it is reviewed again.
Not available yet
Messages arrive over HTTPS only. MLLP over TLS or a VPN, and picking up files from your SFTP server, are not built.
ORM, MDM and VXU messages are refused. Results and hospital events are the whole scope today.
ChartVoyant does not send HL7 v2. To receive data from a practice, see FHIR write to other systems.