Access Encounter Information

Introduction

The Patient/Encounter Platform 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 Platform 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 :

  • period: The start and end time of the encounter (search on a range but not on specific field start or end (more details here)
  • subject/patient: The patient present at the encounter
  • service-provider._extension: Search on UF (Functional Unit) extension to filter on healthcare service

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
_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.

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"
  }
}

Fields description :

FieldsDefinitionFR onlyPossible values
identifier[VN]"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 encounterfalse-
service-providerFonctional Unit in extension or the healthcare structure of this Encounter recordfalse-