POST/transactional-api/create-observation

Create Observation

Records a finalised observation against a patient record. observationType (a SNOMED CT coded entry) is required; supply at most one of the value* properties to carry the observation result. Coded entries are conceptId + description pairs 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-observation' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "observationType": {
      "conceptId": "185389009",
      "description": "Telephone encounter"
    },
    "bodySite": {
      "conceptId": "185389009",
      "description": "Telephone encounter"
    },
    "interpretation": {
      "conceptId": "185389009",
      "description": "Telephone encounter"
    },
    "recordDate": "2026-01-15",
    "observationDate": "2026-01-15",
    "observationTime": "09:30:00",
    "valueCode": {
      "conceptId": "185389009",
      "description": "Telephone encounter"
    },
    "valueString": "Within normal limits.",
    "valueDate": "2026-01-15",
    "valueDateTime": "2026-01-15T09:30:00+00:00",
    "valueQuantity": {
      "value": 120,
      "unit": {
        "conceptId": "185389009",
        "description": "Telephone encounter"
      }
    },
    "valueBloodPressure": {
      "systolic": 120,
      "diastolic": 80
    },
    "additionalInformation": "Repeat reading taken after 5 minutes rest.",
    "consultationTopicHeadingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "hiddenFromPatientFacingServices": false,
    "confidentialFromThirdParties": false
  }'

Body parameters

Field	Type	Required	Description
patientId	string<uuid>	Yes	Medicus patient identifier.
observationType	object	Yes	SNOMED CT coded observation type. Required.
bodySite	object	No	Optional SNOMED CT coded body site.
interpretation	object	No	Optional SNOMED CT coded interpretation.
recordDate	string<date>	No	Record date (YYYY-MM-DD). Defaults to today.
observationDate	string<date>	No	Observation date (YYYY-MM-DD). Defaults to recordDate.
observationTime	string	No	Observation time (HH:MM:SS).
valueCode	object	No	Coded result value (SNOMED CT).
valueString	string	No	Free-text result value.
valueDate	string<date>	No	Date result value (YYYY-MM-DD).
valueDateTime	string<date-time>	No	Date/time result value (ISO 8601 / ATOM).
valueQuantity	object	No	Numeric result value with an optional SNOMED CT coded unit.
valueBloodPressure	object	No	Blood pressure result value.
additionalInformation	string	No	Free-text additional information.
consultationTopicHeadingId	string<uuid>	No	Optional heading to attach the observation to.
hiddenFromPatientFacingServices	boolean	No	If true, hidden from Patient Facing Services (IM1) such as the NHS App.
confidentialFromThirdParties	boolean	No

Responses

200 Observation created.

Response fields

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

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

400 Validation error.

12 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.	a conceptId doesn't resolve to a SNOMED CT code (observationType, bodySite, interpretation, valueCode, or unit)
no-code	You must specify a SNOMED CT code for the observation type.	observationType missing
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-observation-date	The observationDate is not a valid date in Y-m-d format.	observationDate not a valid date in Y-m-d format
invalid-observation-time	The observationTime is not a valid time in H:i:s format.	observationTime not a valid time in H:i:s format
invalid-value-date	The valueDate is not a valid date in Y-m-d format.	valueDate not a valid date in Y-m-d format
invalid-value-date-time	The valueDateTime is not a valid date/time format	valueDateTime not a valid date/time format
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

Response fields

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

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