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 :

FieldsDefinitionFR onlyPossible values
identifier"Visit number" unique identifier for a encounter in a specific hospitaltrueEncounter.identifier.type.coding.system = <http://www.interopsante.org/fhir/valueset/fr-encounter-identifier-type> and Encounter.identifier.type.coding.code = VN
statusStatus of the Encounterfalseplanned or in-progress or finished
subjectThe patient related to the Encounterfalse-
periodThe start and end time of the encounterfalseSearch on a range but not on specific field start or end (more details here)
service-providerFunctional Unit in extension or the healthcare structure of this Encounterfalse-
classClassification of patient encounter contextfalseEMER 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 practitioneraTMs office, 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 parametersDefinitionAvailable for Ramsay SantéAvailable for Vivalto
patientSearch on the patient id you find in the Patient search APItruetrue
dateSearch on start date of the encounter - use FHIR prefixes (ex: gt = greater than). Could be multivalued
(FHIR 'and' operation, ex. date=gt2022-01-01&date=lt2022-10-10. You are limited to 10 values max.
true (but only one date parameter is available)true (but only one date parameter is available)
identifierSearch on the Visit number (VN). VN = unique identifier of the encounter in a care structure (search on exact value only)falsefalse
statusSearch on status of the encounter (planned, in-progress, finished)falsefalse
service-provider._extensionSearch on UF (Functional Unit) extension to filter on healthcare service (search on exact value only)falsefalse
classSearch on the classfalsefalse
_sortSort result by last updated date in our system or by start date of the encounterfalsefalse
_idSearch by the unique identifier of the Lifen system (multivalued supported). You are limited to 10 values max.yesyes
_countNumber of results on the page (max: 100) - 0 not supportedyesyes

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.