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": "string",
      "description": "string"
    },
    "bodySite": {
      "conceptId": "string",
      "description": "string"
    },
    "interpretation": {
      "conceptId": "string",
      "description": "string"
    },
    "recordDate": "2024-07-29",
    "observationDate": "2024-07-29",
    "observationTime": "string",
    "valueCode": {
      "conceptId": "string",
      "description": "string"
    },
    "valueString": "string",
    "valueDate": "2024-07-29",
    "valueDateTime": "2024-07-29T15:51:28.071Z",
    "valueQuantity": {
      "value": 0,
      "unit": {
        "conceptId": "string",
        "description": "string"
      }
    },
    "valueBloodPressure": {
      "systolic": 0,
      "diastolic": 0
    },
    "additionalInformation": "string",
    "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.

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

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

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

Request​

Responses​

Request

Responses