POST/transactional-api/create-patient-request

Create Patient Request

Submits a patient request to Medicus on behalf of a patient. Use medical for clinical concerns and admin for administrative matters. A request is rejected if the organisation has that request type switched off or paused, or is closed or outside the opening hours it has configured for that type, matching the rules the patient portal applies.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/create-patient-request' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "requestType": "medical",
    "requester": "patient",
    "response": [
      {
        "question": "healthConcern",
        "answer": "Persistent chest pain for three days."
      }
    ],
    "isHighPriority": false,
    "proxyDetails": {
      "firstName": "Jane",
      "lastName": "Doe",
      "relationshipToPatient": "Mother"
    },
    "attachments": [
      {
        "fileName": "ecg-result.jpg",
        "contentType": "image/jpeg",
        "data": "/9j/4AAQSkZJRgAB..."
      }
    ]
  }'

Body parameters

Field	Type	Required	Description
`patientId`	`string<uuid>`	Yes	Medicus patient identifier.
`requestType`	`enum`	Yes	Type of patient request. One of: `medical`, `admin`.
`requester`	`enum`	Yes	Who is submitting the request. One of: `patient`, `proxy`.
`response`	`array<object>`	Yes	Question/answer pairs for the request. Must contain at least one item. The `question` value must be one of the fixed keys for the given `requestType`: `medical` accepts `healthConcern` and `recentContact`; `admin` accepts `requestDetails`.
`isHighPriority`	`boolean` (nullable)	No	Whether the request should be flagged as high priority.
`proxyDetails`	`object` (nullable)	No	Required when `requester` is `proxy`. All three fields are required: `firstName` (given name of the proxy), `lastName` (family name of the proxy), `relationshipToPatient` (the proxy's relationship to the patient, e.g. Mother, Carer).
`attachments`	`array<object>` (nullable)	No	Optional file attachments. Maximum 5 attachments, each up to 10 MB. Allowed types: JPEG, PNG, DOC, DOCX.

Responses

200 Patient request created.

Response fields

Field	Type	Description
`patientRequestId`	`string<uuid>`	Identifier of the created patient request.

{
  "patientRequestId": "00000000-0000-0000-0000-000000000000"
}

400 Validation error.

16 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-request-type`	The requestType must be medical or admin	requestType is not medical or admin
`invalid-requester`	The requester must be patient or proxy	requester is not patient or proxy
`missing-proxy-details`	proxyDetails is required when requester is proxy	requester is proxy but proxyDetails is absent
`invalid-proxy-details`	proxyDetails must include firstName, lastName, and relationshipToPatient	proxyDetails is present but missing firstName, lastName, or relationshipToPatient
`too-many-attachments`	A maximum of 5 attachments may be included	more than 5 attachments supplied
`invalid-attachment-content`	Attachment content is not valid base64	attachment data is not valid base64
`attachment-too-large`	Attachment exceeds the 10 MB size limit	attachment exceeds 10 MB
`unsupported-file-type`	Attachment content type is not supported. Allowed types: image/jpeg, image/png, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document	attachment contentType is not jpeg, png, doc, or docx
`empty-response`	response must contain at least one question and answer	response is an empty array
`invalid-question`	Invalid question key. Allowed values for medical requests: healthConcern, recentContact	a response item uses an unrecognised question key
`request-type-disabled`	Medical requests are not enabled for this organisation.	the organisation has this request type switched off; do not retry
`request-type-paused`	Medical requests are temporarily paused for this organisation.	the organisation has paused this request type; safe to retry later
`request-type-closed`	Medical requests are closed for this organisation at this time.	the organisation is closed, or the request is outside the opening hours configured for this request type; safe to retry later

Response fields

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

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

Request​

Responses​

Request

Responses