Payload Format
Tiep supports two payload strategies depending on how tightly you want to align with healthcare interoperability standards:
- Standard HL7 FHIR bundle (default and recommended).
- Custom JSON contract that Tiep transforms on your behalf.
Option 1: Standard HL7 FHIR (default)
Regardless of whether you integrate via API or webhook, Tiep can deliver the same HL7 FHIR JSON structure described in Report Generation. The bundle follows the HL7 FHIR specification with the following structure: + Composition (must be the first entry as per FHIR rules) + Patient + Encounter + Practitioner + Observations: any measurable thing - weight, age, sports - might be many + Conditions: think diagnosis - might be many + MedicationRequests: think medical prescription - ibuprofen, amoxicillin - might be many + ServiceRequests: think an MRI, a lab test, a colonoscopy, etc. - might be many + AllergyIntolerances: think allergy to peaches and how they react. - might be many + CarePlan: how a practitioner intends to deliver care for the patient + ClinicalImpressions: encapsulates a list of resources related to one clinical case.
For instance, if a patient has a broken leg and arm, we encapsulate
all the observations related to the leg in one ClinicalImpression
and the other observations related to the arm in another.
Note how there is only one composition but there can be many clinical impressions. Indeed, a patient is given one report when they leave the doctor's office, but there can be different clinical cases within that report.
Example shoulder consultation payload:
{
"context": {
"additional_metadata": 4,
"is_first_time": true
},
"fhir": {
"resourceType": "Bundle",
"id": "bundle-consultation-example",
"type": "document",
"timestamp": "2024-01-11T10:00:00Z",
"entry": [
{
"fullUrl": "urn:uuid:composition-1",
"resource": {
"resourceType": "Composition",
"id": "composition-1",
"status": "final",
"subject": {
"reference": "Patient/patient-1"
},
"date": "2024-01-11T09:30:00Z",
"author": [
{
"reference": "Practitioner/practitioner-1"
}
],
"title": "Consultation Note",
"section": [
{
"title": "Vitals and Initial Observations",
"text": "Vitals are correct with emphasis on...",
"entry": [
{
"reference": "Observation/obs-1"
},
{
"reference": "Observation/obs-2"
}
]
},
{
"title": "Findings and Plan",
"text": "The plan is to...",
"entry": [
{
"reference": "Observation/obs-3"
},
{
"reference": "MedicationRequest/medrequest-1"
},
{
"reference": "ServiceRequest/srvrequest-1"
}
]
}
]
}
},
{
"fullUrl": "urn:uuid:patient-1",
"resource": {
"resourceType": "Patient",
"id": "patient-1",
"identifier": [
{
"system": "http://examplehospital.org/patients",
"value": "123456"
}
],
"name": [
{
"use": "official",
"family": "Doe",
"given": ["John"]
}
]
}
},
{
"fullUrl": "urn:uuid:practitioner-1",
"resource": {
"resourceType": "Practitioner",
"id": "practitioner-1",
"identifier": [
{
"system": "http://examplehospital.org/providers",
"value": "DR987"
}
],
"name": [
{
"use": "official",
"family": "Smith",
"given": ["Jane"]
}
]
}
},
{
"fullUrl": "urn:uuid:obs-1",
"resource": {
"resourceType": "Observation",
"id": "obs-1",
"status": "final",
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/observation-category",
"code": "vital-signs"
}
]
}
],
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "85354-9",
"display": "Blood pressure panel"
}
]
},
"subject": {
"reference": "Patient/patient-1"
},
"effectiveDateTime": "2024-01-11T09:20:00Z",
"valueString": "Blood Pressure: 120/80 mmHg"
}
},
{
"fullUrl": "urn:uuid:obs-2",
"resource": {
"resourceType": "Observation",
"id": "obs-2",
"status": "final",
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/observation-category",
"code": "laboratory"
}
]
}
],
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "718-7",
"display": "Hemoglobin [Mass/volume] in Blood"
}
]
},
"subject": {
"reference": "Patient/patient-1"
},
"effectiveDateTime": "2024-01-11T09:25:00Z",
"valueQuantity": {
"value": 14.5,
"unit": "g/dL",
"system": "http://unitsofmeasure.org",
"code": "g/dL"
}
}
},
{
"fullUrl": "urn:uuid:obs-3",
"resource": {
"resourceType": "Observation",
"id": "obs-3",
"status": "final",
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/observation-category",
"code": "clinical"
}
]
}
],
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "281798007",
"display": "Physical examination finding"
}
],
"text": "General physical exam"
},
"subject": {
"reference": "Patient/patient-1"
},
"effectiveDateTime": "2024-01-11T09:28:00Z",
"valueString": "Patient reports mild headache and slight dizziness."
}
},
{
"fullUrl": "urn:uuid:medrequest-1",
"resource": {
"resourceType": "MedicationRequest",
"id": "medrequest-1",
"status": "active",
"intent": "order",
"medicationCodeableConcept": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "387517004",
"display": "Ibuprofen 200mg oral tablet"
}
],
"text": "Ibuprofen 200mg Tablet"
},
"subject": {
"reference": "Patient/patient-1"
},
"authoredOn": "2024-01-11T09:45:00Z",
"requester": {
"reference": "Practitioner/practitioner-1"
},
"dosageInstruction": [
{
"text": "Take 1 tablet by mouth every 6 hours as needed for pain",
"timing": {
"repeat": {
"frequency": 1,
"period": 6,
"periodUnit": "h"
}
},
"route": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "26643006",
"display": "Oral route"
}
]
}
}
]
}
},
{
"fullUrl": "urn:uuid:srvrequest-1",
"resource": {
"resourceType": "ServiceRequest",
"id": "srvrequest-1",
"status": "active",
"intent": "order",
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "306006008",
"display": "Magnetic resonance imaging of brain"
}
],
"text": "MRI of the Brain"
},
"subject": {
"reference": "Patient/patient-1"
},
"authoredOn": "2024-01-11T09:50:00Z",
"requester": {
"reference": "Practitioner/practitioner-1"
}
}
}
]
}
}
Option 2: Custom JSON transformation
If your systems already rely on a proprietary JSON schema, Tiep can map your schema to our own. To do so, you must create Integrated Templates:
- You send Tiep the JSON you already generate (no need to map to FHIR), optionally with your desired fields following our schemas.
- Tiep ingests and normalizes that payload internally to create the our own report template that maps to the JSON.
- The response you receive from generating each report mirrors your schema, enriched with the answers and medical content generated by Tiep.
- Then on each consultation:
Reach out to your Tiep integration manager or contact [email protected] to scope the transformation. Once the custom contract is in place, Tiep handles the translation layer so your HIS can continue exchanging data using its native JSON.
Comparison at a glance
| Aspect | Standard HL7 FHIR | Custom JSON transformation |
|---|---|---|
| Interoperability with third-party systems | ✅ Uses a widely adopted standard | ❌ Requires bespoke adapters outside Tiep |
| Initial engineering effort | ❌ Requires mapping to FHIR upfront | ✅ Reuses your existing schema |
| Long-term maintenance | ✅ Stable spec with community tooling | ❌ Dependent on the custom contract staying in sync |