POST/transactional-api/create-inbound-referral

Create Inbound Referral

Atomically creates an inbound referral and a clinical case for the given patient. The referral is always created with ACCEPTED status. If a commissionedServiceId is provided, the case will be included in MHSDS extracts; include reasonForReferral to populate the MHSDS referral reason field.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/create-inbound-referral' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "receivedDate": "2025-01-15",
    "clinicalCaseTypeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "commissionedServiceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reasonForReferral": "string",
    "referringOrganisation": {
      "name": "string",
      "identifierType": "nhs-england-ods-code",
      "identifierValue": "string"
    },
    "additionalDetails": "string"
  }'

Body parameters

Field	Type	Required	Description
patientId	string<uuid>	Yes	Medicus patient identifier. Obtain from the create-patient-record endpoint.
receivedDate	string<date>	Yes	Date the referral was received, in YYYY-MM-DD format.
clinicalCaseTypeId	string<uuid>	Yes	The clinical case type to assign. Obtain from the get-inbound-referral-metadata endpoint.
commissionedServiceId	string<uuid>	No	Optional. The commissioned service to link. Required for MHSDS extract rows to populate. Obtain from the get-inbound-referral-metadata endpoint.
reasonForReferral	string	No	Optional. The MHSDS referral reason. Only recorded when commissionedServiceId is also provided.
referringOrganisation	object	No	Optional. Details of the organisation that made the referral.
additionalDetails	string	No	Optional. Free-text additional details for the referral and case.

Responses

201 Referral and clinical case created successfully.

{
  "referralId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clinicalCaseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

400 Validation error.

13 possible code values

Code	Description	When
missing-patient-id	The patientId is required.	patientId is missing or blank
invalid-patient-id	The patientId is not a UUID.	patientId present but not a UUID
missing-received-date	The receivedDate is required.	receivedDate is missing or blank
invalid-received-date	receivedDate must be a valid date in YYYY-MM-DD format.	receivedDate not a valid YYYY-MM-DD date
missing-clinical-case-type-id	The clinicalCaseTypeId is required.	clinicalCaseTypeId is missing or blank
invalid-clinical-case-type-id	The clinicalCaseTypeId is not a UUID.	clinicalCaseTypeId present but not a UUID
invalid-commissioned-service-id	The commissionedServiceId is not a UUID.	commissionedServiceId present but not a UUID
invalid-reason-for-referral	The reasonForReferral value is not valid.	reasonForReferral present but not a recognised value
invalid-referring-organisation	referringOrganisation must be an object.	referringOrganisation present but not an object
invalid-referring-organisation-name	referringOrganisation.name must be a string.	referringOrganisation.name present but not a string
invalid-organisation-identifier-type	The referringOrganisation.identifierType value is not valid.	referringOrganisation.identifierType present but not a recognised value
invalid-referring-organisation-identifier-value	referringOrganisation.identifierValue must be a string.	referringOrganisation.identifierValue present but not a string
invalid-additional-details	additionalDetails must be a string.	additionalDetails present but not a string

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

404 A referenced entity was not found.

3 possible code values

Code	Description	When
patient-not-found	Patient not found for this patientId.	patientId does not match any patient
clinical-case-type-not-found	Clinical case type not found for this clinicalCaseTypeId.	clinicalCaseTypeId does not match any clinical case type
commissioned-service-not-found	Commissioned service not found for this commissionedServiceId.	commissionedServiceId does not match any commissioned service

{
  "errors": [
    {
      "code": "patient-not-found",
      "description": "Patient not found for this patientId."
    }
  ]
}

422 The clinical case type requires a commissioned service.

{
  "errors": [
    {
      "code": "commissioned-service-required",
      "description": "This clinical case type requires a commissionedServiceId."
    }
  ]
}