FHIR Resources¶

Curaway stores clinical data using the FHIR R4 (Fast Healthcare Interoperability Resources) standard. This ensures interoperability with external EHR systems and provides a well-defined schema for clinical information.

Overview¶

Aspect	Detail
FHIR Version	R4 (4.0.1)
Validation	Pydantic models via the `fhir.resources` Python library
Storage	JSONB columns in PostgreSQL (one column per resource type)
Coding Systems	ICD-10, SNOMED CT, LOINC
Serialization	Standard FHIR JSON; no custom extensions

How FHIR Resources Fit Into Curaway¶

When a patient goes through the intake process, the AI agent collects medical history, symptoms, and procedure details. This information is transformed into FHIR R4 resources and stored alongside the case record. When a case is shared with a provider, the FHIR resources are included as a structured clinical summary that any FHIR-compatible system can consume.

Resource Types¶

Patient¶

Represents the patient undergoing medical travel. Mapped from the Curaway patient profile.

Endpoint: GET /api/v1/fhir/Patient/{patient_id}

Key Fields:

Field	FHIR Path	Description
Name	`Patient.name`	Patient's full name (given + family)
Date of Birth	`Patient.birthDate`	ISO date format
Gender	`Patient.gender`	`male`, `female`, `other`, `unknown`
Contact	`Patient.telecom`	Phone and email
Address	`Patient.address`	Country of residence
Identifier	`Patient.identifier`	Curaway patient ID

Example:

{
  "resourceType": "Patient",
  "id": "pat-a1b2c3d4",
  "identifier": [
    {
      "system": "https://curaway.ai/patient-id",
      "value": "pat-a1b2c3d4"
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Patel",
      "given": ["Aisha"]
    }
  ],
  "gender": "female",
  "birthDate": "1985-06-15",
  "telecom": [
    {
      "system": "email",
      "value": "aisha.patel@example.com"
    },
    {
      "system": "phone",
      "value": "+971501234567"
    }
  ],
  "address": [
    {
      "country": "AE",
      "use": "home"
    }
  ]
}

Condition¶

Represents a medical condition, diagnosis, or reason for seeking treatment. Uses ICD-10 coding.

Endpoint: GET /api/v1/fhir/Condition/{condition_id}

Key Fields:

Field	FHIR Path	Description
Code	`Condition.code`	ICD-10 coded diagnosis
Clinical Status	`Condition.clinicalStatus`	`active`, `recurrence`, `relapse`, `inactive`, `resolved`
Verification	`Condition.verificationStatus`	`confirmed`, `provisional`, `differential`
Subject	`Condition.subject`	Reference to the Patient resource
Onset	`Condition.onsetDateTime`	When the condition first appeared
Note	`Condition.note`	Free-text clinical notes from intake

Example:

{
  "resourceType": "Condition",
  "id": "cond-hip-001",
  "clinicalStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
        "code": "active"
      }
    ]
  },
  "verificationStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
        "code": "confirmed"
      }
    ]
  },
  "code": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/sid/icd-10",
        "code": "M16.1",
        "display": "Primary osteoarthritis, left hip"
      }
    ],
    "text": "Osteoarthritis of the left hip"
  },
  "subject": {
    "reference": "Patient/pat-a1b2c3d4"
  },
  "onsetDateTime": "2024-08-01",
  "note": [
    {
      "text": "Patient reports increasing hip pain over 18 months. Difficulty walking. Conservative treatment (physiotherapy, NSAIDs) has not provided sufficient relief."
    }
  ]
}

Procedure¶

Represents a medical procedure that has been performed or is being planned. Uses SNOMED CT coding.

Endpoint: GET /api/v1/fhir/Procedure/{procedure_id}

Key Fields:

Field	FHIR Path	Description
Code	`Procedure.code`	SNOMED CT coded procedure
Status	`Procedure.status`	`preparation`, `in-progress`, `completed`, `entered-in-error`
Subject	`Procedure.subject`	Reference to the Patient resource
Performed	`Procedure.performedDateTime`	When the procedure was/will be performed
Body Site	`Procedure.bodySite`	Anatomical location
Reason	`Procedure.reasonReference`	Reference to the Condition resource

Example:

{
  "resourceType": "Procedure",
  "id": "proc-hip-replace-001",
  "status": "preparation",
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "76164006",
        "display": "Total hip replacement"
      }
    ],
    "text": "Total hip replacement"
  },
  "subject": {
    "reference": "Patient/pat-a1b2c3d4"
  },
  "reasonReference": [
    {
      "reference": "Condition/cond-hip-001"
    }
  ],
  "bodySite": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "362905007",
          "display": "Left hip joint"
        }
      ]
    }
  ]
}

Observation¶

Represents a clinical measurement or finding. Uses LOINC coding for lab results and vital signs.

Endpoint: GET /api/v1/fhir/Observation/{observation_id}

Key Fields:

Field	FHIR Path	Description
Code	`Observation.code`	LOINC coded observation type
Status	`Observation.status`	`final`, `preliminary`, `amended`
Value	`Observation.valueQuantity`	Numeric result with unit
Subject	`Observation.subject`	Reference to the Patient resource
Effective	`Observation.effectiveDateTime`	When the observation was made
Interpretation	`Observation.interpretation`	`normal`, `high`, `low`, `critical`

Example:

{
  "resourceType": "Observation",
  "id": "obs-hgb-001",
  "status": "final",
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "718-7",
        "display": "Hemoglobin [Mass/volume] in Blood"
      }
    ]
  },
  "subject": {
    "reference": "Patient/pat-a1b2c3d4"
  },
  "effectiveDateTime": "2026-03-20T08:30:00Z",
  "valueQuantity": {
    "value": 13.2,
    "unit": "g/dL",
    "system": "http://unitsofmeasure.org",
    "code": "g/dL"
  },
  "interpretation": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
          "code": "N",
          "display": "Normal"
        }
      ]
    }
  ]
}

DocumentReference¶

Represents an uploaded document (medical report, imaging, insurance letter). Links to the file stored in Cloudflare R2.

Endpoint: GET /api/v1/fhir/DocumentReference/{doc_id}

Key Fields:

Field	FHIR Path	Description
Type	`DocumentReference.type`	Document category (LOINC coded)
Status	`DocumentReference.status`	`current`, `superseded`
Subject	`DocumentReference.subject`	Reference to the Patient resource
Content	`DocumentReference.content`	Attachment with URL, content type, and size
Description	`DocumentReference.description`	Human-readable description
Date	`DocumentReference.date`	When the document was created/uploaded

Example:

{
  "resourceType": "DocumentReference",
  "id": "doc-mri-001",
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "18748-4",
        "display": "Diagnostic imaging study"
      }
    ]
  },
  "subject": {
    "reference": "Patient/pat-a1b2c3d4"
  },
  "date": "2026-03-15T14:00:00Z",
  "description": "MRI of left hip showing osteoarthritis",
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "url": "https://uploads.curaway.ai/tenant-apollo-001/pat-a1b2c3d4/mri-left-hip-2026-03-15.pdf",
        "size": 2458624,
        "title": "MRI Report - Left Hip"
      }
    }
  ]
}

Represents the patient's GDPR consent for data processing and sharing. Mapped from the Curaway consent management system.

Endpoint: GET /api/v1/fhir/Consent/{consent_id}

Key Fields:

Field	FHIR Path	Description
Status	`Consent.status`	`active`, `rejected`, `inactive`
Scope	`Consent.scope`	`patient-privacy` for GDPR consent
Category	`Consent.category`	Type of consent (treatment, research, data sharing)
Patient	`Consent.patient`	Reference to the Patient resource
Date/Time	`Consent.dateTime`	When consent was given
Provision	`Consent.provision`	What data and actions are permitted

Example:

{
  "resourceType": "Consent",
  "id": "consent-gdpr-001",
  "status": "active",
  "scope": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/consentscope",
        "code": "patient-privacy",
        "display": "Privacy Consent"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://loinc.org",
          "code": "59284-0",
          "display": "Consent Document"
        }
      ]
    }
  ],
  "patient": {
    "reference": "Patient/pat-a1b2c3d4"
  },
  "dateTime": "2026-03-15T10:00:00Z",
  "provision": {
    "type": "permit",
    "purpose": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "TREAT",
        "display": "Treatment"
      }
    ],
    "dataPeriod": {
      "start": "2026-03-15",
      "end": "2027-03-15"
    }
  }
}

Coding Systems¶

System	URI	Usage in Curaway
ICD-10	`http://hl7.org/fhir/sid/icd-10`	Condition/diagnosis coding
SNOMED CT	`http://snomed.info/sct`	Procedure and body site coding
LOINC	`http://loinc.org`	Observation types, document categories

Validation¶

All FHIR resources are validated at the API boundary using the fhir.resources Python library, which provides Pydantic-based models for every FHIR R4 resource type:

from fhir.resources.patient import Patient

# Validates against the FHIR R4 Patient schema
patient = Patient.parse_obj(incoming_json)

# Raises ValidationError if the resource is invalid

Validation errors are returned as FHIR_RESOURCE_INVALID_001 with details about which fields failed. See the error codes reference for details.

Storage¶

FHIR resources are stored as JSONB in PostgreSQL, co-located with the case record:

CREATE TABLE case_clinical_data (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    case_id UUID REFERENCES cases(id) NOT NULL,
    resource_type VARCHAR(50) NOT NULL,
    fhir_resource JSONB NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now(),
    updated_at TIMESTAMPTZ DEFAULT now()
);

CREATE INDEX idx_clinical_resource_type ON case_clinical_data(resource_type);
CREATE INDEX idx_clinical_case_id ON case_clinical_data(case_id);

This approach keeps clinical data queryable via PostgreSQL while maintaining full FHIR compliance in the JSON structure.

FHIR Resources¶

Overview¶

How FHIR Resources Fit Into Curaway¶

Resource Types¶

Patient¶

Condition¶

Procedure¶

Observation¶

DocumentReference¶

Consent¶

Coding Systems¶

Validation¶

Storage¶