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 query, create, update, and delete encounters.

The Encounter model

The Encounter model contains all the information about the encounters of a patient. In addition, encounters can also be group-based with more than one contact, they can have a pinned message, and they can be muted.

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
- arrived
- triaged
- in-progress
- onleave
- finished
- cancelled
- entered-in-error
  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.

POST/Encounter

Create a new Encounter

This endpoint allows you to create a new 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": "entered-in-error",
    "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.

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

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "Successfully deleted Encounter/1"
    }
  ]
}