API Reference

All endpoints require a valid RS256 Bearer token from the Auth Server.

Base URL: http://localhost:8083

Referral CRUD

Create referral (draft)

POST /api/referrals
Role: CLINICIAN or ADMIN

Creates a referral in DRAFT status. No consent check at this stage.

Field	Required	Description
patientId	✓	FHIR Patient reference
requesterId	✓	FHIR Practitioner reference of referring clinician
receivingFacilityClientId	✓	SMART client_id of receiving facility
performerId		FHIR Organization reference
referralCode		SNOMED CT code
priority		ROUTINE (default), URGENT, ASAP, STAT
reasonCodes		ICD-10 or SNOMED CT list (max 20)
clinicalNote		Free text (max 2048 characters)
sharedResourceTypes		FHIR resource types to share via consent gate (max 20)
supportingInfo		FHIR references to attached documents (max 20)
occurrenceDate		Intended appointment/procedure date

Response: 201 Created

---

Get referral

GET /api/referrals/{id}
Role: CLINICIAN, ADMIN, or PATIENT

Returns 404 if not found.

---

My referrals (requester view)

GET /api/referrals/my-referrals?page=0&size=20
Role: CLINICIAN or ADMIN

Returns referrals created by the authenticated clinician (identified by JWT subject), newest first. Paginated.

---

Patient's referrals

GET /api/referrals/patient/{patientId}
Role: CLINICIAN or ADMIN, or the patient themselves

---

Receiving facility inbox

GET /api/referrals/inbox?performerId=Organization/royal-london-cardiology
Role: CLINICIAN or ADMIN

Returns all active referrals where performer_id matches. Ordered by priority (STAT first) then created_at ascending.

---

Workflow actions

Send referral

POST /api/referrals/{id}/send
Role: CLINICIAN or ADMIN

Runs the consent gate. Transitions DRAFT → ACTIVE if all consent checks pass.

Success: 200 — updated referral with status: ACTIVE

Consent gate failure: 422

{
  "code":    "CONSENT_GATE_FAILED",
  "message": "Cannot send referral — patient has not consented to share Condition with ..."
}

Invalid state: 422

{
  "code":    "INVALID_TRANSITION",
  "message": "Cannot send referral in status ACTIVE — must be DRAFT"
}

---

Update task status

PATCH /api/referrals/{id}/tasks/{taskId}
Role: CLINICIAN or ADMIN

Used by the receiving facility to progress the workflow.

{
  "status":          "ACCEPTED",
  "note":            "Appointment booked for 15 July at 14:00",
  "rejectionReason": null
}

Valid transitions:

• REQUESTED → RECEIVED, CANCELLED
• RECEIVED → ACCEPTED, REJECTED, CANCELLED
• ACCEPTED → INPROGRESS, CANCELLED
• INPROGRESS → COMPLETED, ONHOLD, FAILED
• ONHOLD → INPROGRESS, CANCELLED

Invalid transitions return 422 with INVALID_TRANSITION.

---

Revoke referral

POST /api/referrals/{id}/revoke?reason=...
Role: CLINICIAN or ADMIN

Cancels all open tasks. The referral and task records are preserved.

---

Hold referral

POST /api/referrals/{id}/hold?reason=...
Role: CLINICIAN or ADMIN

Only valid when status = ACTIVE.

---

Resume referral

POST /api/referrals/{id}/resume
Role: CLINICIAN or ADMIN

Only valid when status = ONHOLD.

---

Tasks

Get tasks for referral

GET /api/referrals/{id}/tasks
Role: CLINICIAN or ADMIN

Returns all tasks for the referral, oldest first.

---

Admin

Stats

GET /api/referrals/stats
Role: ADMIN

{
  "draft":     12,
  "active":    234,
  "completed": 1820,
  "revoked":   43
}

---

Error responses

All errors return RFC 7807 ProblemDetail or the referral module's own error record:

{ "code": "CONSENT_GATE_FAILED", "message": "..." }
{ "code": "INVALID_TRANSITION",  "message": "..." }

HTTP Status	When
201	Referral created
200	Action succeeded
400	Validation failure (missing required field, invalid value)
401	Missing or invalid Bearer token
403	Insufficient role
404	Referral or task not found
422	Consent gate failed or invalid state transition
500	Unexpected server error (details in server log only)

---

Next: Configuration →