Access Patient 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).

Access Control

You need a Machine to 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 a patient

You can search for a patient in 2 different ways : search by name (and other parameters) or by id.

To search a patient by name/other parameters, use the following route : POST {{host}}/fhir/v3/Patient/_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 patients that match the search.

Search parameters :

Parameter	Value type	Description & Restrictions	Example
`name`	string	Combination between "given" and "family" field. Requires minimum 2 characters (3 for Vivalto Santé). This search is based on the beginning of the word.	`dupont`
`family`	string	Requires minimum 2 characters (3 for Vivalto Santé). This search is based on the beginning of each word. Required if you use `given` parameter on Ramsay Santé	`dupo`
`given`	string	Requires minimum 2 characters (3 for Vivalto Santé). This search is based on the beginning of each word. Required if you use `family` parameter on Ramsay Santé	`mar`
`birthdate`	date	Search on exact value only.	`22-10-1990`
`identifier`	string	Patient's IPP (Identifiant Patient Permanent) or INS (Identité Nationale de Santé). Search on exact value only. Not available for Vivalto yet. Multi-value search is available for this param (use `,`to make a OR). You are limited to 10 values max.	`810000` `810000,820000`
`phone`	string	Search on exact value only. Not available for Ramsay Santé or Vivalto Santé yet.	`+33644301200`
`_sort`	string	Can be followed by `_lastUpdated` to sort from the oldest to the most recent or by `-_lastUpdated` to have the most recent results first. Visit the FHIR documentation for more information. Not available for Ramsay Santé or Vivalto Santé yet.	`_lastUpdated`
`_id`	string	Multi-value search is available for this param (use `,`to make a OR). You are limited to 10 values max.	`234` `345,234`
`_count`	int	Number of results on the page (max: 100) - `0` not supported. Not available for Ramsay Santé or Vivalto Santé yet.	`10`

To better understand the FHIR standard definition of each field, you can refer to the FHIR documentation here : FHIR Patient .

📘
The results are sorted by id for Ramsay patients. For all other hospitals, they are sorted by relevance.

📘
Only active patients appear in the search result but you can retrieve a deactivated patient with the id endpoint mentioned below.

Example of CURL query :

curl --request POST \
  --url https://api.post-prod.lifen.fr/fhir/v3/Patient/_search \
  --header 'Authorization: Bearer xxxxxxxxxxxxxx'
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data family=dupont

Example of a bundle resource

{
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 12663,
    "entry": [
        {
            "fullUrl": "https://api.lifen.fr/fhir/v3/Patient/2982512",
            "resource": {
                "resourceType": "Patient",
                "id": "2982512", // on renvoie ici l'id Lifen, Ramsay ou Vivalto sous la forme suivante : ramsay-4684864, vivalto-5888684, 1234666.
                "identifier": [
                    {
                        "use": "official",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://interopsante.org/fhir/valueset/fr-patient-identifier-type",
                                    "version": "1.0",
                                    "code": "PI",
                                    "display": "PI"
                                }
                            ]
                        },
                        "system": "urn:oid:1.2.250.1.71.4.2.2.1987789987",
                        "value": "8cc3819116"
                    },
                ],
                "name": [
                    {
                        "use": "usual",
                        "family": "TRONCARD",
                        "given": [
                            "WANNY"
                        ]
                    },
                    {
                        "use": "official",
                        "family": "TRONCARD",
                        "given": [
                            "WANNY"
                        ]
                    }
                ],
                "telecom": [
                    {
                        "system": "email",
                        "value": "[email protected]"
                    }
                ],
                "gender": "male",
                "birthDate": "2014-07-24",
                "multipleBirthInteger": 1,
            }
        }
    ]
}

Read a patient (by id)

To read a patient, use the following route {{host}}/fhir/v3/Patient/id with :

HTTP Verb = GET
Content-type = application/fhir+json

The response will be a patient resource.

Example of a Patient Resource

{
    "resourceType": "Patient",
    "id": "1234",
    "extension": [
        {
            "url": "http://lifen.fr/fhir/StructureDefinition/Patient/Extension/ReliabilityINS",
            "valueCode": "QUALI"
        },
        {
          "url": "http://hl7.org/fhir/StructureDefinition/birthPlace",
          "valueAddress": {
            "city": "RENNES",
            "district": "35135",
            "postalCode": "35000",
            "country": "FRA"
          }
        }
    ],
    "identifier": [
        {
          "use": "official",
          "type": {
            "coding": [
              {
                "system": "http://interopsante.org/fhir/valueset/fr-patient-identifier-type",
                "version": "1.0",
                "code": "PI",
                "display": "PI"
              }
            ]
          },
          "system": "urn:oid:1.2.250.1.71.4.2.2.4444444444", 
          "value": "3333333333" 
        },
        {
            "use": "official",
            "type": {
                "coding": [
                    {
                        "system": "http://interopsante.org/fhir/valueset/fr-patient-identifier-type",
                        "version": "1.0",
                        "code": "INS-NIR",
                        "display": "NIR définitif"
                    }
                ]
            },
            "system": "urn:oid:1.2.250.1.213.1.4.10",
            "value": "11111111111111111"
        }
    ],
    "name": [
        {
            "use": "official",
            "family": "DURAND",
            "given": [
                "Paulette"
            ],
            "prefix": [
                "Mme"
            ]
        },
        {
            "use": "usual", 
            "family": "Michue",
            "given": [
                "Paulette"
            ],
            "prefix": [
                "Mme"
            ]
        }
    ],
    "gender": "female",
    "birthDate": "1957-06-28",
    "multipleBirthInteger": 1,
    "deceasedDateTime": "2022-01-31T00:00:00+01:00",
    "address": [
        {
            "line": [
              "Pierre-Alain D'ARTAGNAN DE L'HERAULT",
              "14 impasse des fleurs",
              "14000 CAEN"
            ],
            "city": "CAEN",
            "postalCode": "14000",
            "country": "FRANCE"
        }
    ],
    "telecom": [
        {
          "system": "email",
          "value": "[email protected]",
        },
        {
          "system": "phone",
          "value": "+33644301200",
          "use": "mobile"
        }
    ]
}

Fields description :

Fields	Definition	Patient Identity Fields for INS requirement	FR only	Possible values
id	FHIR id	false	false	`1234`. The id of a patient can be `1234`, `ramsay-1234`, or `vivalto-1234`. This is how we guarantee that there won't be any collision.
extension[ReliabilityINS]	Return the status of the Patient INS Reliability	true	true	`QUALI` = qualified, `VALI` = validated, `PROV` = temporary
extension[birthPlace]	Birthplace address of the patient	true	false	`district` = INSEE code
identifier[IPP]	"Identifiant Permanent du Patient" unique identifier for a patient in a specific hospital	false	true	`Patient.identifier.type.coding.system = <http://interopsante.org/fhir/valueset/fr-patient-identifier-type`> and `Patient.identifier.type.coding.code = PI`
identifier[INS-NIR/INS-NIA]	"Identité Nationale de Santé" unique identifier for a patient in France	true	true	`Patient.identifier.type.coding.system = <http://interopsante.org/fhir/valueset/fr-patient-identifier-type`> and `Patient.identifier.type.coding.code = (INS-NIR` or `INS-NIA`)
name[official]	Patient's birthname	true	false	-
name[usual]	Patient's current name	false	false	-
gender	Sex of the patient	true	false	-
birthdate	Birthdate of the patient	true	false	-
address	Current postal address of the patient	false	false	-
telecom[email]	Email of the patient	false	false	-
telecom[phone]	Phone number of the patient. Not available on Vivalto.	false	false	-
multipleBirthInteger	Order of birth if twins or more	false	false	1, 2, ...
deceasedDateTime	Date time of death	false	false	`2022-01-31T00:00:00+01:00`

Patient update and merge

In every hospital, patients change, merge continuously which is why, in order to stay up to date, we recommend that you handle the following processes:

each time you want to use a patient's data, call the Patient/Encounter Platform Service again to update the data (by IPP or ID for example)
if the new fetched data contains the link field (with a type attribute with the value replaced-by), this means that the patient has been merged with another and that it has become obsolete. From now on, you must therefore base yourself on the reference of the Patient present in the link field.

Example of old patient merge :

{
  "resourceType": "Patient",
  "id": "1111111",
  "active": false,
  "link": [
    {
      "type": "replaced-by",
      "other": {
        "reference": "Patient/12345"
      }
    }
  ],
  "name": [
    {
      "use": "usual",
      "family": "Michue",
      "given": [
        "Paulette"
      ],
      "prefix": [
        "MME"
      ]
    }
  ]
}

Access Patient Information

Introduction

Access Control

Search a patient

Search parameters :

📘
The results are sorted by id for Ramsay patients. For all other hospitals, they are sorted by relevance.

📘
Only active patients appear in the search result but you can retrieve a deactivated patient with the id endpoint mentioned below.

Example of a bundle resource

Read a patient (by id)

Example of a Patient Resource

Fields description :

Patient update and merge

Introduction

Access Control

Search a patient

Search parameters :

📘The results are sorted by id for Ramsay patients. For all other hospitals, they are sorted by relevance.

📘Only active patients appear in the search result but you can retrieve a deactivated patient with the id endpoint mentioned below.

Example of a bundle resource

Read a patient (by id)

Example of a Patient Resource

Fields description :

Patient update and merge

📘
The results are sorted by id for Ramsay patients. For all other hospitals, they are sorted by relevance.

📘
Only active patients appear in the search result but you can retrieve a deactivated patient with the id endpoint mentioned below.