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
  }'

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

Responses

200 Note created.

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

400 Validation error.

8 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

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