Encounter

Encounters are an essential part of Atticus. On this page, we’ll dive into the different encounter endpoints you can use to manage encounters programmatically. We'll look at how to create, retrieve, update, and delete encounters.

The Encounter model

The Encounter model contains all the information about the encounters of a patient.

Properties

The Encounter model conforms to the FHIR Encounter resource. The following properties are supported:

Name
resourceType*
Type
'Encounter'
Description
The FHIR resource type. This must be set to 'Encounter'.
Name
status*
Type
code
Description
The status of the encounter. Possible values are: - planned - in-progress - on-hold - discharged - completed - cancelled - discontinued - entered-in-error - unknown \ This is only stored as metadata and does not affect any business logic.
Name
identifier
Type
Identifier[]
Description
An array of Identifier objects for this Encounter (e.g. MRN, SSN). This is the place to store EHR identifiers or hospital identifiers for the patient. More information about identifiers in Atticus can be found here.
Name
subject*
Type
Reference
Description
A FHIR Reference object pointing to the patient which is the subject of the encounter. The reference field must be a literal reference of the form Patient/<id>. Identifier-only references and absolute URLs are rejected with a 422 error. (Inside a transaction Bundle, a bundle-local urn:uuid: reference is also accepted.)

POST/Encounter

Create a new Encounter

This endpoint allows you to create a new Encounter.

Creating an Encounter whose identifier matches an existing Encounter returns a 409 Conflict with issue code duplicate and a Location header pointing at the existing Encounter.

Request

POST

/Encounter

curl -X POST https://reports.tiro.health/fhir/r5/Encounter \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Encounter",
    "status": "planned",
    "subject": {
      "reference": "Patient/123"
    }
  }'

Response

{
  "resourceType": "Encounter",
  "id": "1",
  "status": "planned",
  "subject": {
    "reference": "Patient/123"
  }
}

PUT/Encounter?identifier=<system>|<value>

Conditionally update an Encounter

This endpoint allows you to update an Encounter by matching on specific criteria. A common use case is to update the status of an Encounter. Some systems may want to mark encounters as 'entered-in-error' when they are no longer relevant.
The search criteria are provided as query parameters, and the updated Encounter data is provided in the request body. When no Encounter is found that matches the search criteria, a new Encounter is created.

Request

PUT

/Encounter?identifier=http://hospital.example.org/identifiers/encounters|12345

curl -X PUT "https://reports.tiro.health/fhir/r5/Encounter?identifier=http://hospital.example.org/identifiers/encounters|12345" \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Encounter",
    "status": "in-progress",
    "subject": {
      "reference": "Patient/123"
    }
  }'

Response

{
  "resourceType": "Encounter",
  "id": "1",
  "status": "in-progress",
  "subject": {
    "reference": "Patient/123"
  },
  "identifier": [{
    "system": "http://hospital.example.org/identifiers/encounters",
    "value": "12345"
  }]
}

GET/Encounter/:id

Get an existing Encounter

This endpoint allows you to retrieve an existing Encounter by providing the Encounter id.

Request

GET

/Encounter/1

curl -G https://reports.tiro.health/fhir/r5/Encounter/1 \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \

DELETE/Encounter/:id

Delete an existing Encounter

This endpoint allows you to delete an existing Encounter by providing the Encounter id. Once an Encounter is deleted, it cannot be recovered. A successful delete returns a 204 No Content response with an empty body.

Request

DELETE

/Encounter/1

curl -X DELETE https://reports.tiro.health/fhir/r5/Encounter/1 \
  -H "Authorization: Basic {{apikey}}" \
  -H "Content-Type: application/fhir+json" \

Response

HTTP/1.1 204 No Content