FHIR API

The FHIR API provides healthcare interoperability endpoints for transforming Vantrexia observations into FHIR R4 resources and transmitting them to eClinicalWorks. It supports individual and batch operations, transmission monitoring, and service health checks.

FHIR R4 Compliance

All FHIR resources conform to the HL7 FHIR R4 specification and the US Core Implementation Guide. Observations use LOINC coding and UCUM units for interoperability with any FHIR-compliant EMR system.

Get FHIR Observation

Retrieve a single observation in FHIR R4 Observation resource format.

GET /api/v1/fhir/observations/{uuid}/

Path Parameters

Parameter	Type	Required	Description
`uuid`	`uuid`	Yes	Observation ID

Example Request

curl https://app.vantrexia.com/api/v1/fhir/observations/d4e5f6a7-b8c9-0123-defa-234567890123/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "resourceType": "Observation",
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2026-02-06T10:30:05Z",
    "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-blood-pressure"]
  },
  "status": "final",
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
          "code": "vital-signs",
          "display": "Vital Signs"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "85354-9",
        "display": "Blood pressure panel with all children optional"
      }
    ]
  },
  "subject": {
    "reference": "Patient/d290f1ee-6c54-4b01-90e6-d701748f0851",
    "display": "Jane Doe"
  },
  "effectiveDateTime": "2026-02-06T10:30:00Z",
  "device": {
    "display": "BP-OMRON-7250"
  },
  "component": [
    {
      "code": {
        "coding": [{ "system": "http://loinc.org", "code": "8480-6", "display": "Systolic blood pressure" }]
      },
      "valueQuantity": { "value": 142, "unit": "mmHg", "system": "http://unitsofmeasure.org", "code": "mm[Hg]" }
    },
    {
      "code": {
        "coding": [{ "system": "http://loinc.org", "code": "8462-4", "display": "Diastolic blood pressure" }]
      },
      "valueQuantity": { "value": 92, "unit": "mmHg", "system": "http://unitsofmeasure.org", "code": "mm[Hg]" }
    },
    {
      "code": {
        "coding": [{ "system": "http://loinc.org", "code": "8867-4", "display": "Heart rate" }]
      },
      "valueQuantity": { "value": 78, "unit": "beats/minute", "system": "http://unitsofmeasure.org", "code": "/min" }
    }
  ]
}

Transform Observation

Manually trigger FHIR R4 transformation for a specific observation. Normally transformations happen automatically in the pipeline, but this endpoint allows re-transformation if needed.

POST /api/v1/fhir/observations/{uuid}/transform/

Example Request

curl -X POST https://app.vantrexia.com/api/v1/fhir/observations/d4e5f6a7-b8c9-0123-defa-234567890123/transform/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "observation_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "fhir_status": "pending",
  "transformed_at": "2026-02-06T15:30:00Z",
  "message": "Observation transformed to FHIR R4 format. Queued for transmission."
}

Transmit to eClinicalWorks

Manually trigger transmission of a FHIR observation to eClinicalWorks. The observation must have been transformed first (status must be pending or failed).

POST /api/v1/fhir/observations/{uuid}/transmit/

Example Request

curl -X POST https://app.vantrexia.com/api/v1/fhir/observations/d4e5f6a7-b8c9-0123-defa-234567890123/transmit/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "observation_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "fhir_status": "processing",
  "transmission_id": "TXN-2026-08842",
  "message": "Transmission initiated to eClinicalWorks."
}

Error Response `400 Bad Request`

{
  "detail": "Observation has not been transformed to FHIR format yet.",
  "code": "not_transformed"
}

Process Pending Observations

Trigger batch processing of all pending FHIR observations. This endpoint is normally called by the Celery scheduled task, but can be invoked manually for immediate processing.

POST /api/v1/fhir/process-pending/

Admin Only

This endpoint requires the admin role. Use it sparingly — the automated Celery task handles normal processing every 5 minutes.

Example Request

curl -X POST https://app.vantrexia.com/api/v1/fhir/process-pending/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "processed": 12,
  "succeeded": 10,
  "failed": 2,
  "details": {
    "transformed": 12,
    "transmitted": 10,
    "transmission_errors": [
      { "observation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "error": "eCW connection timeout", "retry_at": "2026-02-06T15:40:00Z" },
      { "observation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "error": "Patient not found in eCW", "retry_at": null }
    ]
  }
}

FHIR Service Status

Check the health and status of the FHIR service, including eClinicalWorks connectivity and queue metrics.

GET /api/v1/fhir/status/

Example Request

curl https://app.vantrexia.com/api/v1/fhir/status/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "status": "healthy",
  "ecw_connection": "connected",
  "ecw_last_successful_transmission": "2026-02-06T15:28:00Z",
  "queue": {
    "pending": 8,
    "processing": 2,
    "failed_awaiting_retry": 3
  },
  "today_stats": {
    "transmitted": 310,
    "failed": 4,
    "success_rate": 0.987
  },
  "uptime": "14d 6h 32m"
}

Transmission Log

Retrieve the transmission history with detailed status and error information for each eClinicalWorks delivery attempt.

GET /api/v1/fhir/transmissions/

Query Parameters

Parameter	Type	Required	Description
`status`	`string`	No	Filter: `pending`, `processing`, `transmitted`, `failed`
`patient_id`	`uuid`	No	Filter by patient
`date_from`	`string`	No	Start date (ISO 8601)
`date_to`	`string`	No	End date (ISO 8601)

Example Request

curl "https://app.vantrexia.com/api/v1/fhir/transmissions/?status=failed&date_from=2026-02-06" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "count": 4,
  "results": [
    {
      "id": "TXN-2026-08830",
      "observation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "patient_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "patient_name": "John Davis",
      "status": "failed",
      "error_message": "eCW connection timeout after 30s",
      "attempt_count": 3,
      "max_attempts": 5,
      "first_attempted_at": "2026-02-06T14:00:00Z",
      "last_attempted_at": "2026-02-06T14:45:00Z",
      "next_retry_at": "2026-02-06T15:30:00Z",
      "observation_type": "blood_pressure"
    },
    {
      "id": "TXN-2026-08832",
      "observation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "patient_id": "e3f4a5b6-c7d8-9012-ef34-567890abcdef",
      "patient_name": "Lisa Chen",
      "status": "failed",
      "error_message": "Patient external_id not found in eClinicalWorks",
      "attempt_count": 5,
      "max_attempts": 5,
      "first_attempted_at": "2026-02-06T14:02:00Z",
      "last_attempted_at": "2026-02-06T15:20:00Z",
      "next_retry_at": null,
      "observation_type": "weight"
    }
  ]
}

Transmission States

Every FHIR observation moves through a defined state machine during the transmission lifecycle:

State	Description
`pending`	Observation has been transformed to FHIR R4 and is queued for transmission
`processing`	Transmission to eClinicalWorks is in progress
`transmitted`	Successfully delivered to eClinicalWorks and acknowledged
`failed`	Transmission failed — will be retried automatically up to 5 times

Pending

The observation has been transformed into a FHIR R4 resource and placed in the transmission queue. It awaits the next processing cycle (every 5 minutes).

Processing

The Celery worker has picked up the observation and is actively transmitting it to eClinicalWorks via the FHIR API.

Transmitted

eClinicalWorks has acknowledged receipt. The observation is recorded as successfully delivered. No further action needed.

Failed

The transmission attempt failed (network error, eCW unavailable, patient not found, etc.). The system will automatically retry with exponential backoff.

Retry Logic

Failed transmissions are retried automatically using exponential backoff with jitter:

Attempt	Delay	Maximum Wait
1st retry	5 minutes	~5 min
2nd retry	15 minutes	~15 min
3rd retry	45 minutes	~45 min
4th retry	2 hours	~2 hr
5th retry (final)	6 hours	~6 hr

Maximum Retries

After 5 failed attempts, the transmission is marked as permanently failed (next_retry_at: null). These require manual intervention — either fix the underlying issue and use the Transmit endpoint to retry, or investigate the error in the Transmission Log.

Common Failure Causes

Connection timeout: eClinicalWorks server is temporarily unavailable — typically resolves on retry.
Patient not found: Patient's external_id does not exist in eClinicalWorks — verify the mapping in Patients API.
Invalid FHIR resource: Observation data does not meet FHIR R4 validation — check the observation for missing required fields.
Authentication error: eCW API credentials have expired — update credentials in Configuration.

Previous Triage API Next Integrations Overview

Get FHIR Observation

Path Parameters

Example Request

Response 200 OK

Transform Observation

Example Request

Response 200 OK

Transmit to eClinicalWorks

Example Request

Response 200 OK

Error Response 400 Bad Request

Process Pending Observations

Example Request

Response 200 OK

FHIR Service Status

Example Request

Response 200 OK

Transmission Log

Query Parameters

Example Request

Response 200 OK

Transmission States

Pending

Processing

Transmitted

Failed

Retry Logic

Response `200 OK`

Response `200 OK`

Response `200 OK`

Error Response `400 Bad Request`

Response `200 OK`

Response `200 OK`

Response `200 OK`