POST/transactional-api/create-encounter

Create Encounter

Creates a finalised encounter (consultation) against a patient record, with one or more topics, each carrying one or more headings. Coded entries are SNOMED CT conceptId + description pairs resolved against the NHS term browser. Optionally, observations, notes, and documents can be filed in the same atomic call: see the observations/notes/documents properties on a heading. Every observation, note, and document filed through this endpoint must be nested under a heading; top-level observations/notes/documents arrays are rejected.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/create-encounter' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "patientId": "4d59c916-9726-11ec-af3f-0a58a9feac02",
    "encounterType": {
      "conceptId": "185389009",
      "description": "Telephone encounter"
    },
    "startDate": "2026-01-15",
    "startTime": "09:00:00",
    "hiddenFromPatientFacingServices": false,
    "confidentialFromThirdParties": false,
    "topics": [
      {
        "code": {
          "conceptId": "185389009",
          "description": "Telephone encounter"
        },
        "headings": [
          {
            "code": {
              "conceptId": "185389009",
              "description": "Telephone encounter"
            },
            "observations": [
              {}
            ],
            "notes": [
              {}
            ],
            "documents": [
              {}
            ]
          }
        ]
      }
    ]
  }'

Body parameters

Field	Type	Required	Description
`patientId`	`string<uuid>`	Yes	Medicus patient identifier.
`encounterType`	`object`	Yes	SNOMED CT coded encounter type. Required.
`startDate`	`string<date>`	No	Encounter start date (YYYY-MM-DD). Defaults to today.
`startTime`	`string`	No	Encounter start time (HH:MM:SS).
`hiddenFromPatientFacingServices`	`boolean`	No	If true, hidden from Patient Facing Services (IM1) such as the NHS App.
`confidentialFromThirdParties`	`boolean`	No
`topics`	`array<object>`	Yes	One or more consultation topics. At least one is required, and each topic must contain at least one heading.

Responses

200 Encounter created. A heading's observations, notes, and documents are only present when the corresponding request array was non-empty.

Response fields

Field	Type	Description
`id`	`string<uuid>`	Identifier of the created encounter.
`topics[].id`	`string<uuid>`
`topics[].code.conceptId`	`string`
`topics[].code.description`	`string`
`topics[].headings[].id`	`string<uuid>`
`topics[].headings[].code.conceptId`	`string`
`topics[].headings[].code.description`	`string`
`topics[].headings[].observations[].id`	`string<uuid>`
`topics[].headings[].notes[].id`	`string<uuid>`
`topics[].headings[].documents[].id`	`string<uuid>`

{
  "id": "00000000-0000-0000-0000-000000000000",
  "topics": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "code": {
        "conceptId": "185389009",
        "description": "Telephone encounter"
      },
      "headings": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "code": {
            "conceptId": "185389009",
            "description": "Telephone encounter"
          },
          "observations": [
            {
              "id": null
            }
          ],
          "notes": [
            {
              "id": null
            }
          ],
          "documents": [
            {
              "id": null
            }
          ]
        }
      ]
    }
  ]
}

400 Validation error.

18 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
`no-encounter-type`	You must specify an encounter type.	encounterType missing
`invalid-start-date`	The startDate is not a valid date in Y-m-d format.	startDate not a valid date in Y-m-d format
`invalid-start-time`	The startTime is not a valid time in H:i:s format.	startTime not a valid time in H:i:s format
`no-topics`	You must specify at least one topic.	topics missing or empty
`no-headings`	You must specify at least one heading.	a topic's headings missing or empty
`no-heading-code`	You must specify a code for the heading.	a heading is missing a code
`unattached-items-not-allowed`	Observations, notes, and documents must be nested under a heading; the top-level observations, notes, and documents arrays are not supported on this endpoint.	a top-level observations, notes, or documents array is non-empty
`no-code`	You must specify a SNOMED CT code for the observation type.	an observation is missing observationType
`no-code-or-text`	You must specify one of code or text	a note has neither code nor text
`invalid-record-date`	The recordDate is not a valid date in Y-m-d format.	an observation, note, or document recordDate is not a valid date in Y-m-d format
`invalid-observation-date`	The observationDate is not a valid date in Y-m-d format.	an observation observationDate is not a valid date in Y-m-d format
`invalid-observation-time`	The observationTime is not a valid time in H:i:s format.	an observation observationTime is not a valid time in H:i:s format
`invalid-value-date`	The valueDate is not a valid date in Y-m-d format.	an observation valueDate is not a valid date in Y-m-d format
`invalid-value-date-time`	The valueDateTime is not a valid date/time format	an observation valueDateTime is not a valid date/time format

Response fields

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

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

Request​

Responses​

Request

Responses