Access Patient Coverage Information


The Patient/Encounter API Service provides you with access to information about patients' administrative profile, patients' coverage 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).


This API is not yet available for patients from Vivalto healthcare structures.

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.

Search Patient Coverage

You can search patient Coverage only with one body param : beneficiary (patient Lifen references)

You need to get the Patient FHIR reference from the Access Patient Information

To search a patient coverage by patient parameter, use the following route : POST {{host}}/fhir/v3/Coverage/_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 coverage that match the search.

Search parameters :

Parameter     Value typeDescription & RestrictionsExample
beneficiarystringFHIR reference of the Patient in Lifen system (Patient/xxxx)
Multi-value search is available for this param (use ,to make a OR) except for Ramsay. You are limited to 10 values max.

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

Example of CURL query :

curl --request POST \
  --url \
  --header 'Authorization: Bearer xxxxxxxxxxxxxx'
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data beneficiary=Patient/23435345

Example of a bundle resource

  "resourceType": "Bundle",
  "meta": {
    "lastUpdated": "2023-01-23T16:37:18.692+00:00"
  "type": "searchset",
  "total": 1,
  "entry": [
      "resource": {
        "resourceType": "Coverage",
        "identifier": [
            "use": "official",
            "type": {
              "coding": [
                  "system": "",
                  "code": "NH"
            "system": "urn:oid:",
            "value": "[NIR-OD]"
        "status": "active",
        "beneficiary": {
          "reference": "Patient/[id]"
        "payor": [
            "reference": "Organization/21793798"
      "search": {
        "mode": "match"

Fields description :

FieldsTypeDefinitionPossible values
identifierstringNIR/NIA-OD of the patient2950244162294
statusstringstatus of the Coverage resourceactiveby default
beneficiaryvalueReferenceFHIR reference of the patient you search forPatient/3435434
payorvalueReferenceFHIR reference of the AMO or AMC issuer organizationOrganization/34345