> 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/integration-guides/choosing-format.md).

# Choosing a Data Format

How to choose between JSON, HL7, and FHIR formats for submitting blood test data.

BloodGPT accepts blood test data in **JSON** and **HL7** formats, with **FHIR R4** support coming soon. All formats are processed identically — choose the one that fits your existing infrastructure.

## Quick Decision

{% hint style="success" %}
**Simple rule:** Use whatever format you already have. Don't convert between formats — both work the same way.
{% endhint %}

| Your Situation                    | Recommended Format     | Why                             |
| --------------------------------- | ---------------------- | ------------------------------- |
| Your LIS outputs HL7 messages     | **HL7**                | No conversion needed, use as-is |
| Building custom integration       | **JSON**               | Easier to construct and debug   |
| Have structured data in database  | **JSON**               | Direct mapping to JSON objects  |
| Receiving data from lab equipment | **HL7**                | Standard lab equipment output   |
| Your system uses FHIR R4          | **FHIR** (coming soon) | Native FHIR Bundle intake       |
| Not sure                          | **JSON**               | More flexible, human-readable   |

## Format Comparison

### JSON Format

```json
{
  "patient_id": "PAT-001",
  "external_id": "TEST-2025-001",
  "patient_info": {
    "birth_date": "1985-03-25",
    "gender": "male"
  },
  "payload": {
    "test_date": "2025-01-15T10:00:00Z",
    "parameters": [
      {
        "name": "Glucose",
        "value": 95,
        "unit": "mg/dL",
        "range": "70-100"
      }
    ]
  }
}
```

**Pros:**

* Human-readable
* Easy to debug
* Flexible structure
* Works with any HTTP client

**Cons:**

* Requires manual mapping from lab systems

### HL7 v2.x Format

```
MSH|^~\&|LIS|LAB|BLOODGPT|API|20250115100000||ORU^R01|MSG001|P|2.5
PID|1||PAT-001||Doe^John||19850325|M
OBR|1|TEST-2025-001||CBC^Complete Blood Count
OBX|1|NM|2345-7^Glucose^LN||95|mg/dL|70-100|N|||F
```

**Pros:**

* Industry standard for lab data
* Direct output from LIS systems
* No transformation needed

**Cons:**

* Less readable
* Fixed structure

## When to Use HL7

Use HL7 if your Laboratory Information System (LIS) already produces HL7 messages:

```mermaid
flowchart LR
    A[Lab Analyzer] --> B[LIS]
    B -->|HL7 message| C[BloodGPT API]
    C --> D[Interpretation]
```

Common LIS systems that output HL7:

* Cerner
* Epic
* MEDITECH
* Sunquest
* SoftLab

See [HL7 Format documentation](/submitting-tests/hl7.md) for detailed specifications.

## When to Use JSON

Use JSON if you're building a custom integration or have structured data:

```mermaid
flowchart LR
    A[Your Database] --> B[Your Backend]
    B -->|JSON| C[BloodGPT API]
    C --> D[Interpretation]
```

Ideal scenarios:

* Wellness platforms receiving data from partner labs
* Mobile apps collecting user-entered data
* Custom healthcare applications
* Integration testing and development

See the [Processing API](/submitting-tests/process.md) for JSON specifications.

## FHIR R4 (Coming Soon)

{% hint style="info" %}
**FHIR R4 support is on our roadmap.** You'll be able to submit FHIR Bundles with DiagnosticReport and Observation resources directly. If you're building a new integration on FHIR — use JSON for now, and we'll provide a migration path when FHIR input is available.
{% endhint %}

FHIR R4 will be ideal for:

* EHR systems with native FHIR APIs (Epic, Cerner)
* Health Information Exchanges (HIE)
* Modern healthcare platforms built on FHIR
* Organizations already using SMART on FHIR

## Converting Between Formats

{% hint style="warning" %}
**Avoid conversion if possible.** If your source outputs HL7, send HL7. If your source has JSON, send JSON. Conversion adds complexity and potential for errors.
{% endhint %}

If you must convert:

* **HL7 → JSON**: Parse OBX segments, map to parameters array
* **JSON → HL7**: Build ORU^R01 message with proper segments

Most integrations don't need conversion — use your native format.