Orders Service — API Contracts

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template

1. Base URL

/api/v1 (internal Kong routing); FHIR base: /fhir/R4

All requests require:

• Authorization: Bearer <JWT> (Keycloak)
• X-Tenant-ID: <tenantId>
• Module entitlement: clinical.orders

---

2. Orders

POST /v1/orders

Create an order (any type). Order is created in draft state; CDS checks run before persisting.

Roles: CLINICIAN, PRESCRIBER

Request body (medication example):

{
  "patientId": "pat_01J...",
  "encounterId": "enc_01J...",
  "orderType": "medication",
  "orderCode": { "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "1049502", "display": "Amoxicillin 500mg" },
  "medicationDetail": {
    "medicationCode": { "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "1049502", "display": "Amoxicillin 500mg" },
    "dose": 500,
    "doseUnit": "mg",
    "route": "oral",
    "frequency": "TDS",
    "durationDays": 7,
    "prn": false
  },
  "priority": "routine",
  "notes": "For pneumonia",
  "clientMutationId": "uuid-idempotency-key"
}

Response 201:

{
  "orderId": "ord_01J...",
  "patientId": "pat_01J...",
  "orderType": "medication",
  "status": "draft",
  "cdsAlerts": [],
  "version": 1,
  "createdAt": "2026-04-18T09:00:00Z"
}

If CDS alerts present:

{
  "orderId": "ord_01J...",
  "status": "draft",
  "cdsAlerts": [
    {
      "alertId": "cds_01J...",
      "level": "warning",
      "ruleId": "DDI-AMOX-WARFARIN",
      "message": "Potential interaction: Amoxicillin + Warfarin. Monitor INR.",
      "acknowledged": false
    }
  ]
}

Error codes: PATIENT_NOT_FOUND (404), PATIENT_DECEASED (422), ENCOUNTER_INACTIVE (422), DUPLICATE_MUTATION (409).

---

POST /v1/orders/:id/activate

Transition order from draft to active. Requires all hard-stops resolved and warnings acknowledged.

Roles: CLINICIAN, PRESCRIBER

Response 200: { "orderId": "...", "status": "active" }

Error codes: CDS_HARD_STOP (422), CDS_WARNING_UNACKNOWLEDGED (422), ORDER_TERMINAL_STATE (409).

---

POST /v1/orders/:id/cds-alerts/:alertId/acknowledge

Acknowledge a CDS warning alert.

Roles: CLINICIAN, PRESCRIBER

Request body: { "reason": "Patient aware of interaction; benefit outweighs risk", "version": 1 }

Response 200: { "alertId": "...", "acknowledged": true }

---

GET /v1/orders/:id

Get a single order with full detail.

Roles: CLINICIAN, NURSE, PATIENT (own)

Response 200: Full Order object including cdsAlerts[], medicationDetail/labDetail/etc., history.

---

GET /v1/orders

List orders with filters.

Roles: CLINICIAN, NURSE, PATIENT (own)

Query params: patientId (required for non-admin), encounterId, orderType, status, from, to, priority, page, pageSize

---

PUT /v1/orders/:id/cancel

Cancel an active or draft order.

Roles: CLINICIAN, PRESCRIBER

Request body: { "reason": "Patient refused medication", "version": 1 }

Response 200: { "orderId": "...", "status": "cancelled" }

---

PUT /v1/orders/:id/hold

Place an active order on hold.

Roles: CLINICIAN

Request body: { "reason": "Patient NBM pre-surgery", "version": 1 }

Response 200: { "orderId": "...", "status": "on-hold" }

---

PUT /v1/orders/:id/resume

Resume a held order.

Roles: CLINICIAN

Request body: { "version": 1 }

Response 200: { "orderId": "...", "status": "active" }

---

PUT /v1/orders/:id/correction

Mark an order as entered-in-error.

Roles: CLINICIAN, ADMIN

Request body: { "reason": "Ordered for wrong patient", "version": 1 }

Response 200: { "orderId": "...", "status": "entered-in-error" }

---

3. Order Sets

POST /v1/order-sets

Create an order set template.

Roles: CLINICIAN, ADMIN

Request body:

{
  "name": "Community Acquired Pneumonia Adult",
  "description": "Standard CAP management orders",
  "orderTemplates": [
    { "orderType": "medication", "orderCode": { "code": "1049502", "system": "rxnorm", "display": "Amoxicillin 500mg" }, "medicationDetail": { "dose": 500, "doseUnit": "mg", "route": "oral", "frequency": "TDS", "durationDays": 7 } },
    { "orderType": "laboratory", "orderCode": { "code": "58410-2", "system": "LOINC", "display": "CBC" }, "labDetail": { "priority": "routine" } }
  ]
}

Response 201: { "orderSetId": "ords_01J...", "name": "...", "orderCount": 2 }

---

GET /v1/order-sets

List order set templates.

Roles: CLINICIAN, ADMIN

Query params: orderType, search, page, pageSize

---

POST /v1/order-sets/:setId/instantiate

Instantiate an order set for a patient and encounter.

Roles: CLINICIAN, PRESCRIBER

Request body: { "patientId": "pat_01J...", "encounterId": "enc_01J..." }

Response 201:

{
  "orderIds": ["ord_01J...", "ord_02J..."],
  "cdsAlerts": [ /* aggregate alerts from all created orders */ ]
}

---

4. Referrals

GET /v1/orders/referrals/:id

Get full referral detail including tracking status.

Roles: CLINICIAN, PATIENT (own)

Response 200:

{
  "orderId": "ord_01J...",
  "orderType": "referral",
  "status": "active",
  "referralDetail": {
    "referralType": "internal",
    "referToFacilityId": "fac_02J...",
    "referToSpecialty": "Cardiology",
    "urgency": "routine",
    "clinicalSummary": "Suspected atrial fibrillation; ECG attached",
    "scheduledAppointmentId": null,
    "referralStatus": "pending_scheduling"
  }
}

---

GET /v1/orders/referrals

List referrals with status.

Roles: CLINICIAN, ADMIN

Query params: patientId, referToFacilityId, referralStatus, urgency, from, to, page, pageSize

---

5. Batch Orders

POST /v1/orders/batch

Create multiple orders in a single request (not order-set based).

Roles: CLINICIAN, PRESCRIBER

Request body: { "orders": [ /* array of CreateOrder payloads */ ] }

Response 207 Multi-Status:

{
  "results": [
    { "index": 0, "orderId": "ord_01J...", "status": "draft", "success": true },
    { "index": 1, "success": false, "error": { "code": "CDS_HARD_STOP", "message": "..." } }
  ]
}

---

6. FHIR R4 Surface

FHIR resource	Operation	Path	Notes
ServiceRequest	read	GET /fhir/R4/ServiceRequest/:id	lab, radiology, procedure, referral, nursing, activity orders
ServiceRequest	search	GET /fhir/R4/ServiceRequest?patient=:id&status=&category=
MedicationRequest	read	GET /fhir/R4/MedicationRequest/:id	medication orders
MedicationRequest	search	GET /fhir/R4/MedicationRequest?patient=:id&status=
NutritionOrder	read	GET /fhir/R4/NutritionOrder/:id	diet orders
NutritionOrder	search	GET /fhir/R4/NutritionOrder?patient=:id&status=
Task	read	GET /fhir/R4/Task/:id	order fulfillment tasks