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.

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.

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

400 Validation error.

13 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

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