Access Encounter Information

Introduction

The Patient/Encounter API Service provides you with access to information about patients' administrative profile and patients' encounters.

This information is usually stored in hospitals' Patient Administrative Systems (PAS - in french GAM Gestion Administrative des Malades ou GAP Gestion Administrative des Patients).

A patient can be hospitalized in different departments. Stays are represented by the FHIR resource Encounter.

Access Control

You need a Machine To Machine Communications to use this API.

You need to have the PATIENT_GAM_SEARCH scope to access the Patient/Encounter Platform service. This functional scope will give you access to the following technical scopes : ORGANIZATION_READ , PATIENT_READ , PATIENT_SEARCH , ENCOUNTER_READ , ENCOUNTER_SEARCH.

Search an Encounter

You can search for an encounter in 2 different ways : search by patient name (and other parameters) or by id.

To search a patient by patient name/other parameters, use the following route : POST {{HOST}}/fhir/v3/Encounter/_search

The Patient/Encounter API Service uses the _search feature from FHIR with :

HTTP Verb = POST
Content-type = application/x-www-form-urlencoded

The response will be a Bundle resource that contains all the encounters that match the search.

An Encounter contains several fields :

Fields	Definition	FR only	Possible values
identifier	"Visit number" unique identifier for a encounter in a specific hospital	true	`Encounter.identifier.type.coding.system = <http://www.interopsante.org/fhir/valueset/fr-encounter-identifier-type`> and `Encounter.identifier.type.coding.code = VN`
status	Status of the Encounter	false	`planned` or `in-progress` or `finished`
subject	The patient related to the Encounter	false
period	The start and end time of the encounter	false	Search on a range but not on specific field start or end (more details here)
service-provider	Functional Unit in extension or the healthcare structure of this Encounter	false
class	Classification of patient encounter context	false	`EMER` for Emergency (A patient encounter that takes place at a dedicated healthcare service delivery location where the patient receives immediate evaluation and treatment, provided until the patient can be discharged or responsibility for the patient's care is transferred elsewhere) `IMP` for Inpatient (A patient encounter where a patient is admitted by a hospital or equivalent facility, assigned to a location where patients generally stay at least overnight and provided with room, board, and continuous nursing service) `PRENC` for Pre-admission (A patient encounter where patient is scheduled or planned to receive service delivery in the future, and the patient is given a pre-admission account number. When the patient comes back for subsequent service, the pre-admission encounter is selected and is encapsulated into the service registration, and a new account number is generated) `AMB` for Ambulatory (A comprehensive term for health care provided in a healthcare facility (e.g. a practitioner, a clinic setting, or hospital) on a nonresident basis. The term ambulatory usually implies that the patient has come to the location and is not assigned to a bed. Sometimes referred to as an outpatient encounter) `REC` for Recurring (A patient encounter where patient is scheduled to receive healthcare every week, month or other repeating frequency) `UNK` for Unknown

Example of an Encounter returned by the API :

{
  "resourceType": "Encounter",
  "id": "1224",
  "identifier": [
    {
      "use": "official",
      "type": {
        "coding": [
          {
            "system": "http://www.interopsante.org/fhir/valueset/fr-encounter-identifier-type",
            "version": "3.0.1",
            "code": "VN",
            "display": "Visit Number"
          }
        ]
      },
      "system": "urn:oid:1.2.250.1.71.4.2.2.111111111111111",
      "value": "111111111",
      "assigner": {
        "reference": "Organization/xxxxxx"
      }
    }
  ],
  "status": "finished",
  "subject": {
    "reference": "Patient/xxxxx"
  },
  "period": {
    "start": "2020-12-22T09:00:00+01:00",
    "end": "2021-01-06T12:00:00+01:00"
  },
  "serviceProvider": {
    "extension": [
      {
        "url": "http://lifen.fr/fhir/StructureDefinition/Encounter/ServiceProvider/Extension/FonctionalUnit-1.0",
        "valueString": "400"
      }
    ],
    "reference": "Organization/xxxxxx"
  },
  "class": {
  	"code": 'REC',
    "display": 'Recurring',
    "system": 'http://lifen.fr/fhir/CodeSystem/Encounter/Class'
	}

It is possible to search an encounter via the following parameters :

Search parameters	Definition	Available for Ramsay Santé	Available for Vivalto
`patient`	Search on the patient id you find in the Patient search API	true	true
`date`	Search on date of the encounter. Can use FHIR prefixes (available prefixes: `gt`, `ge`, `lt`, `le`). Can be multivalued (FHIR 'and' operation, ex. `date=gt2022-01-01&date=lt2022-10-10`). You are limited to 10 values max.	true Can use FHIR prefixes Cannot be multivalued, provide only one date parameter at most	true Cannot use FHIR prefixes Cannot be multivalued, provide only one date parameter at most
`identifier`	Search on the Visit number (VN). VN = unique identifier of the encounter in a care structure (search on exact value only)	false	false
`status`	Search on status of the encounter (`planned`, `in-progress`, `finished`)	false	false
`service-provider._extension`	Search on UF (Functional Unit) extension to filter on healthcare service (search on exact value only)	false	false
`class`	Search on the class	false	false
`_sort`	Sort result by last updated date in our system or by start date of the encounter	false	false
`_id`	Search by the unique identifier of the Lifen system (multivalued supported). You are limited to 10 values max.	yes	yes
`_count`	Number of results on the page (max: 100) - `0` not supported	yes	yes

To learn more about the definitions of the other fields, you can look at the definition of the fields here : FHIR Encounter DSTU3

Examples of CURL queries :

curl --request POST \
  --url '{{HOST}}/fhir/v3/Encounter/_search' \
  --header 'Authorization: Bearer {{TOKEN}}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'date=gt2022-02-02'

curl --request POST \
  --url '{{HOST}}/fhir/v3/Encounter/_search' \
  --header 'Authorization: Bearer {{TOKEN}}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'patient=Patient/12345'

curl --request POST \
  --url '{{HOST}}/fhir/v3/Encounter/_search' \
  --header 'Authorization: Bearer {{TOKEN}}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'service-provider._extension=http://lifen.fr/fhir/StructureDefinition/Encounter/ServiceProvider/Extension/FonctionalUnit-1.0|500'

Read an Encounter

To read an encounter, use the following route {{HOST}}/fhir/v3/Encounter/{{id}} with :

HTTP Verb = GET
Content-type = application/fhir+json

The response will be an encounter resource.