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 encounterservice-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 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 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) |
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 |
_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.
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 :
Fields | Definition | FR only | Possible values |
---|---|---|---|
identifier[VN] | "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 | - |
service-provider | Fonctional Unit in extension or the healthcare structure of this Encounter record | false | - |
Updated 2 days ago