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

Specificities for Ramsay Santé and Vivalto Santé hospitals

Ramsay Santé and Vivalto Santé 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/Patient
  • in the production environment : api.lifen.ramsaygds.fr/fhir/v3/Patient

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

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 typeDescription & RestrictionsExample
namestringCombination between "given" and "family" field.
Requires minimum 2 characters (3 for Vivalto Santé).
This search is based on the beginning of the word.
dupont
familystringRequires minimum 2 characters (3 for Vivalto Santé).
This search is based on the beginning of each word.
dupo
givenstringRequires minimum 2 characters (3 for Vivalto Santé).
This search is based on the beginning of each word.
mar
birthdatedateSearch on exact value only.22-10-1990
identifierstringPatient's IPP (Identifiant Patient Permanent) or INS (Identité Nationale de Santé).
Search on exact value only.
Not available for Vivalto yet.
810000
phonestringSearch on exact value only.
Not available for Ramsay Santé or Vivalto Santé yet.
+33644301200
_sortstringCan 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
_lastUpdated

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

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

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.post-prod.lifen.fr/fhir/dstu3/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": "maiden",
                        "family": "TRONCARD",
                        "given": [
                            "WANNY"
                        ]
                    },
                    {
                        "use": "official",
                        "family": "TRONCARD",
                        "given": [
                            "WANNY"
                        ]
                    }
                ],
                "telecom": [
                    {
                        "system": "email",
                        "value": "[email protected]"
                    }
                ],
                "gender": "male",
                "birthDate": "2014-07-24"
            }
        }
    ]
}

Read a patient (by id)

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

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",
    "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 :

FieldsDefinitionPatient Identity Fields for INS requirementFR onlyPossible values
idFHIR idfalsefalse1234. 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 ReliabilitytruetrueQUALI = qualified, VALI = validated, PROV = temporary
extension[birthPlace]Birthplace address of the patienttruefalsedistrict = INSEE code
identifier[IPP]"Identifiant Permanent du Patient" unique identifier for a patient in a specific hospitalfalsetruePatient.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 FrancetruetruePatient.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 birthnametruefalse-
name[usual]Patient's current namefalsefalse-
genderSex of the patienttruefalse-
birthdateBirthdate of the patienttruefalse-
addressCurrent postal address of the patientfalsefalse-
telecom[email]Email of the patientfalsefalse-
telecom[phone]Phone number of the patientfalsefalse-

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