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"
    },
    "isSelfReferral": true,
    "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. Ignored when isSelfReferral is true.
`isSelfReferral`	`boolean`	No	Optional, defaults to false. Set to true when the patient referred themselves, rather than being referred by an external organisation. referringOrganisation is ignored when this is true.
`additionalDetails`	`string`	No	Optional. Free-text additional details for the referral and case.

Responses

201 Referral and clinical case created successfully.

Response fields

Field	Type	Description
`referralId`	`string<uuid>`	The ID of the created inbound referral.
`clinicalCaseId`	`string<uuid>`	The ID of the created clinical case.

{
  "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

Response fields

Field	Type	Description
`errors[].code`	`string`
`errors[].description`	`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

Response fields

Field	Type	Description
`errors[].code`	`string`
`errors[].description`	`string`

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

422 The clinical case type requires a commissioned service.

Response fields

Field	Type	Description
`errors[].code`	`string`
`errors[].description`	`string`

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

Request​

Responses​

Request

Responses