> For the complete documentation index, see [llms.txt](https://docs.bloodgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloodgpt.com/submitting-tests/hl7.md).

# HL7 Format

Submit blood test data using HL7 v2.x laboratory messages

BloodGPT supports HL7 v2.x ORU^R01 (Observation Result) messages for direct integration with Laboratory Information Systems (LIS).

## Quick Start

Upload an HL7 file to the same `/api/v1/process` endpoint:

```bash
curl -X POST https://sandbox.bloodgpt.com/api/v1/process \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@blood-test.hl7" \
  -F 'data={"external_id":"ext-123","patient_id":"pat-456"}'
```

The response format is identical to JSON and PDF submissions.

***

## Supported Format

| Property        | Value                        |
| --------------- | ---------------------------- |
| HL7 Version     | 2.3, 2.4, 2.5, 2.5.1         |
| Message Type    | ORU^R01 (Observation Result) |
| File Extensions | `.hl7`, `.txt`               |
| Encoding        | UTF-8 (recommended), ASCII   |

***

## Supported Segments

```mermaid
graph LR
    MSH[MSH<br/>Header] --> PID[PID<br/>Patient]
    PID --> OBR[OBR<br/>Order]
    OBR --> OBX[OBX<br/>Result]
    OBX --> NTE[NTE<br/>Notes]
```

### MSH — Message Header

| Field               | Position | Description        | Example             |
| ------------------- | -------- | ------------------ | ------------------- |
| Sending Application | MSH-3    | Source system      | `LabSystem`         |
| Sending Facility    | MSH-4    | Laboratory name    | `Memorial Hospital` |
| Message DateTime    | MSH-7    | Creation timestamp | `20240115103000`    |
| Message Type        | MSH-9    | Must be `ORU^R01`  | `ORU^R01`           |

### PID — Patient Identification

| Field         | Position | Description         | Example      |
| ------------- | -------- | ------------------- | ------------ |
| Patient ID    | PID-3    | Patient identifier  | `12345`      |
| Patient Name  | PID-5    | `Last^First^Middle` | `Doe^John^M` |
| Date of Birth | PID-7    | `YYYYMMDD`          | `19850320`   |
| Sex           | PID-8    | `M`, `F`, or `O`    | `M`          |

### OBX — Observation Result

| Field              | Position | Description                   | Example               |
| ------------------ | -------- | ----------------------------- | --------------------- |
| Set ID             | OBX-1    | Sequence number               | `1`                   |
| Value Type         | OBX-2    | `NM` (numeric), `ST` (string) | `NM`                  |
| Observation ID     | OBX-3    | `Code^Name^System`            | `718-7^Hemoglobin^LN` |
| Observation Value  | OBX-5    | Result value                  | `14.5`                |
| Units              | OBX-6    | Unit of measurement           | `g/dL`                |
| Reference Range    | OBX-7    | Normal range                  | `12.0-16.0`           |
| Abnormal Flag      | OBX-8    | See table below               | `H`                   |
| Observation Status | OBX-11   | See table below               | `F`                   |

### NTE — Notes and Comments

| Field   | Position | Description | Example          |
| ------- | -------- | ----------- | ---------------- |
| Set ID  | NTE-1    | Note number | `1`              |
| Comment | NTE-3    | Note text   | `Fasting sample` |

{% hint style="info" %}
NTE segments following an OBX are included as notes for that specific parameter. Standalone NTE segments appear as general footnotes in the report.
{% endhint %}

***

## Abnormal Flags (OBX-8)

| Flag | Meaning          | Interpretation                        |
| ---- | ---------------- | ------------------------------------- |
| `N`  | Normal           | Within reference range                |
| `H`  | High             | Above reference range                 |
| `L`  | Low              | Below reference range                 |
| `A`  | Abnormal         | Outside reference range (unspecified) |
| `HH` | Critical High    | Critically high, immediate attention  |
| `LL` | Critical Low     | Critically low, immediate attention   |
| `HU` | High Upper Panic | Above upper panic limit               |
| `LU` | Low Lower Panic  | Below lower panic limit               |

***

## Observation Status (OBX-11)

| Status | Meaning                              |
| ------ | ------------------------------------ |
| `F`    | Final result                         |
| `P`    | Preliminary result                   |
| `C`    | Corrected result (replaces previous) |
| `X`    | Cannot be obtained                   |
| `I`    | Pending                              |

***

## Sample HL7 Message

```
MSH|^~\&|LabSystem|Memorial Hospital|BloodGPT|API|20240115103000||ORU^R01|MSG001|P|2.4
PID|||12345^^^Hospital||Doe^John^M||19850320|M
OBR|1||LAB001|CBC^Complete Blood Count|||20240115
OBX|1|NM|718-7^Hemoglobin^LN||14.5|g/dL|12.0-16.0|N|||F
OBX|2|NM|789-8^Red Blood Cells^LN||5.2|10*12/L|4.5-5.5|N|||F
OBX|3|NM|4544-3^Hematocrit^LN||42|%|38-50|N|||F
OBX|4|NM|2345-7^Glucose^LN||126|mg/dL|70-100|H|||F
NTE|1||Patient was fasting for 12 hours
OBX|5|NM|2093-3^Cholesterol^LN||220|mg/dL|<200|H|||F
NTE|1||Recommend lipid panel follow-up
```

### What BloodGPT Extracts

From the sample above:

| Source       | Extracted Data                                |
| ------------ | --------------------------------------------- |
| MSH-4        | Laboratory: `Memorial Hospital`               |
| PID-5        | Patient: `Doe, John M`                        |
| PID-7        | Birth Date: `1985-03-20`                      |
| PID-8        | Gender: `male`                                |
| OBX segments | 5 blood parameters with values, units, ranges |
| OBX-8        | Abnormal flags (Glucose: H, Cholesterol: H)   |
| NTE segments | Notes attached to relevant parameters         |

***

## Request Examples

{% tabs %}
{% tab title="File Upload" %}

```bash
curl -X POST https://sandbox.bloodgpt.com/api/v1/process \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@blood-test.hl7" \
  -F 'data={
    "external_id": "ext-123",
    "patient_id": "pat-456"
  }'
```

{% endtab %}

{% tab title="File URL" %}

```bash
curl -X POST https://sandbox.bloodgpt.com/api/v1/process \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ext-123",
    "patient_id": "pat-456",
    "file_url": "https://your-server.com/files/blood-test.hl7"
  }'
```

{% endtab %}
{% endtabs %}

***

## Response

The response is identical to other input formats:

```json
{
  "request_id": "req_abc123",
  "status": "processing",
  "test_id": "clxyz123456",
  "external_id": "ext-123",
  "download_url": "https://cdn.bloodgpt.com/results/report.pdf?sig=..."
}
```

***

## Troubleshooting

<details>

<summary><strong>422 Unprocessable Entity: Invalid HL7 format</strong></summary>

Ensure your file:

* Starts with `MSH|^~\&`
* Uses `|` as field separator
* Has `ORU^R01` in MSH-9
* Contains at least one OBX segment

</details>

<details>

<summary><strong>Missing parameters in results</strong></summary>

Check that OBX segments have:

* Valid LOINC or local codes in OBX-3
* Numeric value in OBX-5 (for `NM` type)
* Units in OBX-6

</details>

<details>

<summary><strong>Patient info not extracted</strong></summary>

Verify PID segment format:

* Date of birth should be `YYYYMMDD` (e.g., `19850320`)
* Sex should be `M`, `F`, or `O`
* Name format: `LastName^FirstName^MiddleName`

</details>