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.