POST/transactional-api/create-note

Create Note

Creates a clinical note against a patient record. Provide free-text text, a SNOMED CT coded entry via code, or both; at least one is required.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/create-note' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "text": "Patient called to confirm medication review.",
    "code": {
      "conceptId": "185389009",
      "description": "Telephone encounter"
    },
    "recordDate": "2026-01-15",
    "consultationTopicHeadingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "hiddenFromPatientFacingServices": false,
    "confidentialFromThirdParties": false,
    "patientBannerFlags": [
      "risk-to-self"
    ]
  }'

Body parameters

Field	Type	Required	Description
patientId	string<uuid>	Yes	Medicus patient identifier.
text	string	No	Free-text note body. Required unless code is supplied.
code	object	No	SNOMED CT coded entry. Required unless text is supplied; resolved against the NHS term browser.
recordDate	string<date>	No	Record date (YYYY-MM-DD). Defaults to today.
consultationTopicHeadingId	string<uuid> (nullable)	No
hiddenFromPatientFacingServices	boolean	No	If true, hidden from Patient Facing Services (IM1) such as the NHS App.
confidentialFromThirdParties	boolean	No
patientBannerFlags	array<string>	No	Patient banner flag types to raise. Omit or leave empty to raise none. Each item one of: risk-to-self, risk-to-others, risk-from-others, local-reasonable-adjustment, medico-legal.

Responses

200 Note created.

Response fields

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

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

400 Validation error.

9 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-code	Could not resolve conceptId into a SNOMED CT code. Check the NHS term browser.	code conceptId doesn't resolve to a SNOMED CT code
no-code-or-text	You must specify one of code or text	neither code nor text supplied
invalid-consultation-topic-heading-id	The consultationTopicHeadingId is not a UUID	consultationTopicHeadingId not a UUID
consultation-topic-heading-not-found	Consultation topic heading not found for this consultationTopicHeadingId	consultationTopicHeadingId doesn't exist
invalid-record-date	The recordDate is not a valid date in Y-m-d format.	recordDate not a valid date in Y-m-d format
invalid-patient-banner-flag	Each entry in patientBannerFlags must be one of the recognised patient banner flag types.	patientBannerFlags contains a value that is not a recognised patient banner flag type

Response fields

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

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