POST/transactional-api/create-document

Create Document

Files a document against a patient record. The file content is supplied base64-encoded in data. Optionally tag the document with a SNOMED CT code and/or clinicalSpecialty, both resolved against the NHS term browser.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/create-document' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "patientId": "4d59c916-9726-11ec-af3f-0a58a9feac02",
    "code": {
      "conceptId": "185389009",
      "description": "Telephone encounter"
    },
    "clinicalSpecialty": {
      "conceptId": "185389009",
      "description": "Telephone encounter"
    },
    "authorDepartment": "Cardiology",
    "additionalInformation": "Patient counselled on medication changes.",
    "title": "Discharge Summary",
    "data": "JVBERi0xLjQK...",
    "fileName": "discharge-summary.pdf",
    "contentType": "application/pdf",
    "consultationTopicHeadingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "hiddenFromPatientFacingServices": false
  }'

Body parameters

Field	Type	Required	Description
patientId	string<uuid>	Yes	Medicus patient identifier.
code	object (nullable)	No	SNOMED CT coded entry for the document. Resolved against the NHS term browser.
clinicalSpecialty	object (nullable)	No	SNOMED CT coded clinical specialty. Resolved against the NHS term browser.
authorDepartment	string (nullable)	No	Department of the filing author.
additionalInformation	string (nullable)	No	Free-text additional information about the document.
title	string (nullable)	No	Document title.
data	string (nullable)	No	Base64-encoded file content.
fileName	string (nullable)	No	Original file name.
contentType	string (nullable)	No	MIME content type of the file.
consultationTopicHeadingId	string<uuid> (nullable)	No
hiddenFromPatientFacingServices	boolean	No	If true, hidden from Patient Facing Services (IM1) such as the NHS App.

Responses

200 Document created.

Response fields

Field	Type	Description
id	string<uuid>	Identifier of the created document.

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

400 Validation error.

6 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
invalid-code	Could not resolve conceptId into a SNOMED CT code. Check the NHS term browser.	conceptId doesn't resolve to a SNOMED CT code
invalid-clinical-specialty	Could not resolve conceptId into a SNOMED CT clinical specialty. Check the NHS term browser.	clinicalSpecialty conceptId doesn't resolve
invalid-consultation-topic-heading-id	The consultationTopicHeadingId is not a UUID	consultationTopicHeadingId is not a UUID
consultation-topic-heading-not-found	Consultation topic heading not found for this consultationTopicHeadingId	consultationTopicHeadingId belongs to another patient's record

Response fields

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

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

404 No patient found for the given patientId.

Response fields

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

{
  "errors": [
    {
      "code": "patient-not-found",
      "description": "Patient not found for the id: 3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ]
}