Access Appointment Information
Introduction
The Appointment API Service provides you with access to information about appointments in a hospital.
The current version of the Appointment API Service gives access to appointments as registered by the hospitals. All ressources linked to the appointment are referenced by identifier (i.e. business identifier) and not by literal reference (i.e. reference through a FHIR technical id of the ressource).
Some identifiers may be used to access ressources on other API (ex. Lifen Patient/Encounter API Services for Patient or Encounter, Annuaire Santé for Practitioners), others may be internal identifiers for ressources that are not accessible outside the hospital.
Although it is mostly the case, reference to a Patient or to an Encounter in the Appointment API Service doesn’t imply that the corresponding resource is available through LifenPatient/Encounter API Service.
Access Control
You need a Machine To Machine Communications to use this API.
You need to have the APPOINTMENT_GAM_SEARCH scope to access the Appointment API service.
This functional scope will give you access to the following technical scopes : APPOINTMENT_READ , APPOINTMENT_SEARCH.
Search an appointment
You can search for an appointment in 2 different ways : search by search parameters (ex. date, patient identifier, practitioner identifier…) or read by id (see section Read an Appointment).
To search an appointment by search parameters, use the following route : POST {{host}}/fhir/v3/Appointment/_search
The Appointment 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 appointments that match the search.
Search parameters
| Parameter | Value type | Description & Restrictions | Example |
|---|---|---|---|
identifier | string | Identifier of the appointment as assigned by placer or by filler. Search on exact value only. Note: Only the value of the identifier is to be provided here, system|identifier format is not supported yet | RDV43654, 5437, 34-APP-436 |
patient-identifier | string | Patient local identifier (IPP) assigned by the hospital. Note: Only the value of the identifier is to be provided here, system|identifier format is not supported yet | ID43654, 3230654, PAT-54474 |
practitioner-identifier | string | Practitioner identifier as provided by the hospital. May be PS_IdNat format or local identifier format. Note: Only the value of the identifier is to be provided here, system|identifier format is not supported yet | 801234534765, MED-43675 |
encounter-identifier | string | Identifier of the encounter to which the appointment is linked. Expression: Appointment.supportingInformation.where(resolve() is Encounter) | VN-43765, 4344756, VENUE4345765 |
status | token | possible values booked or cancelled or noshow or entered-in-error or waitlist or arrived or fullfilled | booked |
date | date | Search on date of the appointment. Can use FHIR prefixes (available prefixes: gt, ge, lt, le). Can be multivalued (FHIR 'and' operation, ex. date=gt2022-01-01&date=lt2022-10-10). You are limited to 10 values max. | 2026-06-13 |
_sort | string | Can be followed by date to sort from the oldest to the most recent or by -date | -date |
_count | int | Number of results on the page (max: 100) - 0 not supported | 10 |
To better understand the FHIR standard definition of each field, you can refer to the FHIR documentation here : FHIR Appointment.
Example of CURL query
curl --request POST \
--url https://api.post-prod.lifen.fr/fhir/v3/Appointment/_search \
--header 'Authorization: Bearer xxxxxxxxxxxxxx'
--header 'Content-Type: application/x-www-form-urlencoded' \
--data date=2026-06-12Example of a bundle resource
{
"resourceType": "Bundle",
"type": "searchset",
"total": 2,
"entry": [
{
"fullUrl": "https://api.lifen.fr/fhir/v3/Appointment/1590811279:APT-c7aff434",
"resource": {
"resourceType": "Appointment",
"id": "1590811279:APT-c7aff434",
"identifier": [
{
"value": "APT-c7aff434"
},
{
"value": "57658"
}
],
"status": "booked",
"reasonCode": [
{
"coding": [
{
"code": "MEQH001",
"system": "urn:oid:1.2.250.1.213.2.5",
"display": "Arthrographie de l'epaule"
}
]
}
],
"supportingInformation": [
{
"type": "Encounter",
"identifier": {
"value": "VN-dca702b2"
}
},
{
"type": "Location",
"identifier": {
"value": "SALLE-28"
}
},
{
"display": "RAD-57",
"identifier": {
"value": "45476",
"system": "urn:lifen:1590811279:REF_EQUIP_LOURD"
}
}
],
"start": "2026-06-12T10:05:00Z",
"comment": "Epaule gauche",
"participant": [
{
"actor": {
"type": "Patient",
"identifier": {
"value": "18a24195"
}
}
},
{
"actor": {
"type": "Practitioner",
"identifier": {
"value": "4576e43",
"system": "urn:lifen:1590811279:ID-INT"
}
}
}
]
}
},
{
"fullUrl": "https://api.lifen.fr/fhir/v3/Appointment/1590811279:APT-c7aff467",
"resource": {
"resourceType": "Appointment",
"id": "1590811279:APT-c7aff467",
"identifier": [
{
"value": "APT-c7aff467"
},
{
"value": "A-54643"
}
],
"status": "booked",
"reasonCode": [
{
"coding": [
{
"code": "NBQK001",
"system": "urn:oid:1.2.250.1.213.2.5",
"display": "Radiographie de la cuisse"
}
]
}
],
"supportingInformation": [
{
"type": "Encounter",
"identifier": {
"value": "VN-5478"
}
},
{
"type": "Location",
"identifier": {
"value": "SALLE-34"
}
},
{
"display": "RAD-53",
"identifier": {
"value": "45423",
"system": "urn:lifen:1590811279:REF_EQUIP_LOURD"
}
}
],
"start": "2026-06-12T15:05:00Z",
"comment": "Cuisse droite",
"participant": [
{
"actor": {
"type": "Patient",
"identifier": {
"value": "25b57324"
}
}
},
{
"actor": {
"type": "Practitioner",
"identifier": {
"value": "4346d547",
"system": "urn:lifen:1590811279:ID-INT"
}
}
}
]
}
}
]
}
Read an appointment (by id)
To read an appointment, use the following route {{host}}/fhir/v3/Appointment/id with :
- HTTP Verb =
GET - Content-type =
application/fhir+json
The response will be an appointment resource.
Example of an Appointment Resource
{
"resourceType": "Appointment",
"id": "1590811279:APT-c7aff497",
"identifier": [
{
"value": "APT-c7aff497"
},
{
"value": "4537654A"
}
],
"status": "booked",
"reasonCode": [
{
"coding": [
{
"code": "ANEST-PRE-OP",
"system": "urn:lifen:1590811279:MOTIF_RDV",
"display": "Consultation d'anesthésie préopératoire"
}
]
}
],
"supportingInformation": [
{
"type": "Encounter",
"identifier": {
"value": "VN-365d57"
}
},
{
"type": "Location",
"identifier": {
"value": "B-28674"
}
}
],
"start": "2026-06-14T14:30:00Z",
"participant": [
{
"actor": {
"type": "Patient",
"identifier": {
"value": "5437654"
}
}
},
{
"actor": {
"type": "Practitioner",
"identifier": {
"value": "801040756478",
"system": "urn:oid:1.2.250.1.71.4.2.1",
"typeCode": "RPPS"
}
}
}
]
}Fields description
| Fields | Cardinality | Definition / Content |
|---|---|---|
| identifier | [0..2] | |
| identifier.value | within identifier [1..1] | Identifier of the appointment as assigned by placer or by filler. |
| status | [1..1] | supported codes: booked , cancelled , noshow , entered-in-error , waitlist , arrived , fullfilled |
| reasonCode | [0..*] | |
| reasonCode.coding.code | within reasonCode [1..1] | reasonCode as provided by the hospital |
| reasonCode.coding.display | within reasonCode [0..1] | display of reasonCode as provided by the hospital |
| reasonCode.coding.system | within reasonCode [0..1] | System in urn format derived from assigning authority name provided by the hospital (see section “Translation of assigning authority name provided by the hospital into FHIR complaint system”) |
| supportingInformation | [0..*] | |
| supportingInformation.type | within supportingInformation [0..1] | For supportingInformation referring to an encounter, valued at Encounter For supportingInformation referring to a location, valued at Location For other type of supportingInformation (from AIG segments in the SIU message), not used |
| supportingInformation.identifier.value | within supportingInformation [1..1] | Identifier as provided by the hospital. If no identifier is provided no corresponding supportingInformation is created |
| supportingInformation.identifier.system | within supportingInformation [0..1] | For supportingInformation referring to a location, not used For supportingInformation referring to an encounter and other type of supportingInformation, system in urn format derived from assigning authority name provided by the hospital (see section “Translation of assigning authority name provided by the hospital into FHIR complaint system”) |
| supportingInformation.display | within supportingInformation [0..1] | Display as provided by the hospital |
| start | [0..1] | Beginning date and hour of the appointment |
| comment | [0..1] | Comment(s) provided by the hospital. If several comments are provided in the SIU message, they are all concatenated in this field separated by a line feed |
| participant | [0..*] | |
| participant.type | within participant [1..1] | For participant referring to a patient, valued at Patient For participant referring to a practitioner, valued at Practitioner |
| participant.actor.identifier.value | within participant [1..1] | Identifier as provided by the hospital. If no identifier is provided no corresponding actor is created |
| participant.actor.identifier.system | within participant [0..1] | For actor referring to a patient, not used For actor referring to a practitioner, system in urn format derived from assigning authority name provided by the hospital (see section “Translation of assigning authority name provided by the hospital into FHIR complaint system”) |
| participant.actor.identifier.type.coding.code | within participant [0..1] | For actor referring to a patient, not used For actor referring to a practitioner, type of identifier as provided by the hospital |
Translation of assinging authority and coding system names provided by the hospital into FHIR compliant system
| Assigning authority / coding system name provided by the hospital | System used in Appointment resources |
|---|---|
| CCAM | urn:oid:1.2.250.1.213.2.5 |
| LN | http://loinc.org |
| SNOMED-CT | http://snomed.info/sct |
| SCT | http://snomed.info/sct |
| RPPS | urn:oid:1.2.250.1.71.4.2.1 |
| ADELI | urn:oid:1.2.250.1.71.4.2.1 |
| FINESS | urn:oid:1.2.250.1.71.4.2.2 |
| any other assigning authority / coding system name | urn:lifen:XXX:YYY with XXX the databaseReference for the hospital and YYY the name of the assigning authority / coding system as provided by the hospital |
Note: Hospitals are asked to provide RPPS and ADELI identifiers in PS_IdNat format (see section 5.4 of Annexe Transverse – Source des données métier pour les professionnels et les structures) and FINESS identifiers in Struct_IdNat format (see section 5.5 of Annexe Transverse – Source des données métier pour les professionnels et les structures). However, developers are advised that compliance to PS_IdNat and Struct_IdNat formats is not enforced and the identifiers exposed are the ones provided by hospitals (without modification).