Guides
Developer Portal (sandbox)Developer Portal (production)Lifen Platform status
Start typing to search…

Access Patient Information

Introduction

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

Available for Ramsay Santé

Available for Vivalto

name

string

Combination between "given" and "family" field.
Requires minimum 2 characters
This search is based on the beginning of the word.

dupont

true

true (but minimum* 3** characters)*

family

string

Requires minimum 2 characters.
This search is based on the beginning of each word.

dupo

true (butrequired if you use given parameter)

true (but minimum3 characters)

given

string

Requires minimum 2 characters.
This search is based on the beginning of each word.

mar

true (butrequired if you use family parameter)

true (but minimum3 characters)

birthdate

date

Search on exact value only.

2014-12-01

true

true

identifier

string

Patient's IPP (Identifiant Patient Permanent) or INS (Identité Nationale de Santé).
Search on exact value only.
Multi-value search is available for this param (use ,to make a OR). You are limited to 10 values max.

810000
810000,820000

true. Cannot be multivalued, provide only one identifier parameter at most

false

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

_lastUpdated

false

false

_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

true

true

_count

int

Number of results on the page (max: 100) - 0 not supported.

10

false

false

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": "DUPONT",
                        "given": [
                            "WANNY"
                        ]
                    },
                    {
                        "use": "official",
                        "family": "TRONCARD",
                        "given": [
                            "WANNY", "PAUL", "PIERRE"
                        ]
                    }
                ],
                "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 {{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": "IRODOUER",
            "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": "257063513511151"
        }
    ],
    "name": [
        {
            "use": "official",
            "family": "DURAND",
            "given": [
                "Paulette", "Marie", "Julie"
            ],
            "prefix": [
                "Mme"
            ]
        },
        {
            "use": "usual", 
            "family": "Michue",
            "given": [
                "Paulette"
            ],
            "prefix": [
                "Mme"
            ]
        }
    ],
    "gender": "female",
    "birthDate": "1957-06-28",
  	"multipleBirthInteger": 1,
    "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]

Status/reliability of the Patient INS

false

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) and
Patient.identifier.system= urn:oid:1.2.250.1.213.1.4.10 for INS-NIR in test environment but Patient.identifier.system= urn:oid:1.2.250.1.213.1.4.8 for INS-NIR in production and Patient.identifier.system= urn:oid:1.2.250.1.213.1.4.9 for INS-NIA in test and production

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

Updated 17 days ago