Payload format
Payload means the data Tiep sends back after a report is saved or generated.
The facility decides the payload type.
SIMPLE payload
SIMPLE is the easiest payload to understand.
It has:
context: the data your HIS attached to the session. Tiep replacesdoctor_id, omitshistory, and preserves patient and episode objects. See consultation context for the rules.payload: the form answers Tiep extracted or the doctor saved.
Example:
{
"context": {
"doctor_id": "doctor-123",
"visit_id": "visit-456",
"department": "orthopedics"
},
"payload": {
"reason": "Shoulder pain after tennis",
"pain-level": 6,
"diagnoses": ["M75.1"],
"plan": "Start physical therapy twice per week"
}
}
The payload object follows the form keys.
If the form has this field:
{
"reason": {
"title": "Reason for visit",
"type": "string"
}
}
Then the payload can include:
{
"reason": "Shoulder pain after tennis"
}
Coded answers
For coded answers, Tiep stores the code.
Form:
{
"title": "Diagnosis",
"type": "string",
"oneOf": [
{ "const": "M75.1", "title": "Rotator cuff tear" }
]
}
Payload:
{
"diagnosis": "M75.1"
}
The HIS gets the stable code, not the display label.
HL7 and FHIR payloads
Use HL7 or FHIR-style payloads when your HIS expects healthcare interoperability resources.
HL7_V2 is the one to choose. It keeps the same two-part shape as SIMPLE, so the
context block reads exactly the same way. Only the second key changes:
| Key | What is inside |
|---|---|
context | The same block described in consultation context. |
hl7 | A FHIR Bundle of type document. |
FHIR payloads can include resources like:
| Resource | Simple meaning |
|---|---|
Composition | The final clinical document. |
Patient | The patient. |
Encounter | The visit. |
Practitioner | The doctor. |
Observation | Measurements or findings. |
Condition | Diagnoses or problems. |
MedicationRequest | Prescriptions. |
ServiceRequest | Requested tests or procedures. |
AllergyIntolerance | Allergies. |
CarePlan | Planned care. |
Example HL7_V2 payload:
{
"context": {
"doctor_id": "doctor-123",
"visit_id": "visit-456"
},
"hl7": {
"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"
}
}
}
]
}
}
The legacy HL7_V1_0 payload
HL7_V1_0 is kept for integrations built before HL7_V2 existed. Do not pick it for new
work, and expect a different shape: instead of a bundle under hl7, it returns a single
FHIR Appointment resource with context and report added next to the FHIR fields.
Its appointment specialty uses the optional SNOMED code configured on the form's facility
specialty. When no code is configured, Tiep emits General medicine (394802001) as the
fallback.
Comparison at a glance
| Choice | Easier to build | Better for standards |
|---|---|---|
SIMPLE | Yes | No |
HL7_V2 | No | FHIR-style support |
HL7_V1_0 | No | Legacy only, do not choose it today |
When payload appears
Session polling returns the payload only after the report is saved.
Before report_saved, the payload is not final.
A pending session is one the doctor paused for later, so it has no payload either.
Read session status for what each state means.