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.

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": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "encounterType": {
      "conceptId": "string",
      "description": "string"
    },
    "startDate": "2024-07-29",
    "startTime": "string",
    "hiddenFromPatientFacingServices": false,
    "confidentialFromThirdParties": false,
    "topics": [
      {
        "code": {
          "conceptId": "string",
          "description": "string"
        },
        "headings": [
          {
            "code": {
              "conceptId": "string",
              "description": "string"
            }
          }
        ]
      }
    ]
  }'

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.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "topics": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "code": {
        "conceptId": "string",
        "description": "string"
      },
      "headings": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "code": {
            "conceptId": "string",
            "description": "string"
          }
        }
      ]
    }
  ]
}

400 Validation error.

10 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

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