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.

Specificities for Ramsay and Vivalto hospitals

Ramsay and Vivalto hospitals have some technical specificities. Lifen Platform abstracts most of them but some custom behaviors persist. They will be specified in this documentation.

For Ramsay Santé, the url is :

  • in the dev environment : api.post-prod.lifen.ramsaygds.fr/fhir/v3/Encounter
  • in the production environment : api.lifen.ramsaygds.fr/fhir/v3/Encounter

Get in touch with your account manager to know if you are connected to a Ramsay Santé structure

For other healthcare structures, the url is :

  • in the dev environment : api.post-prod.lifen.fr/fhir/v3/Encounter
  • in the production environment : api.lifen.fr/fhir/v3/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
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

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 : GET {{HOST}}/fhir/v3/Encounter/{{id}}

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-