POST/transactional-api/create-outbound-referral

Create Outbound Referral

Creates an outbound referral against a patient record. Supply a SNOMED CT coded reason via code (required). If a ubrn is provided the referral is created as an NHS e-RS referral; otherwise a manual referral is created. Optional file attachments are base64-encoded.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/create-outbound-referral' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "code": {
      "conceptId": "string",
      "description": "string"
    },
    "referralDate": "2024-07-29",
    "priority": "string",
    "ubrn": "string",
    "referredToOrganisation": {
      "name": "string"
    },
    "referredToPractitioner": {
      "name": "string"
    },
    "additionalInformation": "string",
    "consultationTopicHeadingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "hiddenFromPatientFacingServices": false,
    "confidentialFromThirdParties": false,
    "attachments": [
      {
        "fileName": "string",
        "contentType": "string",
        "data": "string"
      }
    ]
  }'

Body parameters

Field	Type	Required	Description
patientId	string<uuid>	Yes	Medicus patient identifier.
code	object	Yes	SNOMED CT coded referral reason. Required; resolved against the NHS term browser.
referralDate	string<date>	No	Referral date (YYYY-MM-DD). Defaults to today.
priority	string	No	Outbound referral priority.
ubrn	string	No	Unique Booking Reference Number. When present, the referral is created as an NHS e-RS referral.
referredToOrganisation	object	No	Object with: name.
referredToPractitioner	object	No	Object with: name.
additionalInformation	string	No
consultationTopicHeadingId	string<uuid> (nullable)	No
hiddenFromPatientFacingServices	boolean	No	If true, hidden from Patient Facing Services (IM1) such as the NHS App.
confidentialFromThirdParties	boolean	No
attachments	array<object>	No	File attachments to file against the referral.

Responses

200 Referral created.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

400 Validation error.

9 possible code values

Code	Description	When
missing-patient-id	The patientId is required	patientId missing
invalid-patient-id	The patientId is not valid	patientId not a valid UUID
patient-not-found	Patient not found for this patientId	patientId doesn't exist
invalid-code	Could not resolve conceptId into a SNOMED CT code. Check the NHS term browser.	code conceptId doesn't resolve to a SNOMED CT code
no-code	You must specify a code for the referral.	code missing
invalid-referral-date	The referralDate is not a valid date in Y-m-d format.	referralDate not a valid date in Y-m-d format
invalid-priority	The priority is not a valid outbound referral priority.	priority not a valid outbound referral priority
invalid-consultation-topic-heading-id	The consultationTopicHeadingId is not a UUID	consultationTopicHeadingId not a UUID
consultation-topic-heading-not-found	Consultation topic heading not found for this consultationTopicHeadingId	consultationTopicHeadingId doesn't exist

{
  "errors": [
    {
      "code": "missing-patient-id",
      "description": "The patientId is required"
    }
  ]
}