---
title: Retrieve Appointment
slug: retrieve-appointment
docTags: 
createdAt: 2023-09-12T11:07:57.410Z
---

Access a patient's upcoming and past appointments from their Electronic Health Record (EHR). This data is pivotal for applications in streamlining scheduling processes, ensuring timely care delivery, and optimizing healthcare provider resources. By understanding appointment history, applications can enhance patient engagement and improve overall healthcare efficiency.

To access this clinical data you'll need the patient identifier, obtainable through the [Retrieve Patient](docId:8OPknnbMTaZ47Rk5HkDD3) interaction.

### Interaction

Retrieving the list of allergies and/or intolerances can be done by sending a **GET** to the Appointment endpoint:

`https://api.<region>.founda.com/1/health/organizations/<org-x>/fhir/4/Appointment?<parameters>`

Where `<region>` should be defined according to the different Founda [regions](docId\:ncFf15xNu1WGlST2wNm-P) and `<org-x>` should be replaced with the Healthcare Provider's organization ID that you are integrated with.&#x20;

The response contains a Bundle with 0, 1 or N matching Appointments. The full Appointment resource can be retrieved with the identifier of the selected Appointment from the result set.&#x20;

### Profile

Founda adheres to recognized standards (IHE, HL7 FHIR) to ensure compatibility and harmonization among diverse systems. If there is a profile available for an interaction, it is recommended and preferred to follow the prescribed transactions.

The Retrieve Appointment interaction with the Founda Platform is based on the IHE FHIR Scheduling profile's [ITI-117 transaction](https://build.fhir.org/ig/IHE/ITI.Scheduling/ITI-117.html).&#x20;

### Parameters

To fetch scheduled appointments for a patient, the following search parameters are available.

| **Parameter** | **Type**               | **Required** | **Description**                                                                                     |
| ------------- | ---------------------- | ------------ | --------------------------------------------------------------------------------------------------- |
| `_id`         | `token`                |              | Logical ID of the appointment                                                                       |
| `patient`     | `reference`            | Y            | The patient to retrieve the Allergy and Intolerance overview for                                    |
| `date`        | `date` or `date range` |              | A date range for the appointment start date                                                         |
| `status`      | `string`               |              | Value from [FHIR appointment status ValueSet](https://hl7.org/fhir/valueset-appointmentstatus.html) |

### Example API calls

::::CodeDrawer{title="Retrieve Appointment for Patient" isResponseExpanded="true" autoGeneratedAnchorSlug="retrieve-appointment-for-patient" legacyHash="bDT8_sDX3bFLl86Jc1o_n"}
:::CodeblockTabsExamples
```curl
curl --location 'https://api.eu.founda.com/1/health/organizations/org-4c5739ba994d4ce9b5255d3f84a2d367/fhir/4/Appointment?patient=2078' \
--header 'Authorization: Bearer ory_at_lxKm9XWNa_iR270XfyrdTGIOt7hvAaqg6_FGBTCeB5w.65SHDrnOqKDlBvh_-uFXC9oAOZom63jeFpx_7yBeB_M'
```
:::

:::CodeblockTabsResponses
```javascript
{
    "resourceType": "Bundle",
    "id": "346c53d4-db77-4748-895c-af1e0f1938cc",
    "meta": {
        "lastUpdated": "2023-10-16T13:57:26.796+00:00"
    },
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "https://api.eu.founda.com/1/health/organizations/org-4c5739ba994d4ce9b5255d3f84a2d367/fhir/4/Appointment?patient=2078"
        }
    ],
    "entry": [
        {
            "fullUrl": "https://api.eu.founda.com/1/health/organizations/org-4c5739ba994d4ce9b5255d3f84a2d367/fhir/4/Appointment/2095",
            "resource": {
                "resourceType": "Appointment",
                "id": "2095",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2023-10-05T14:29:15.606+00:00",
                    "source": "#YppUJShqwA645exI",
                    "tag": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
                            "code": "HTEST",
                            "display": "test health data"
                        }
                    ]
                },
                "text": {
                    "status": "generated",
                    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Brian MRI results discussion</div>"
                },
                "status": "booked",
                "serviceCategory": [
                    {
                        "coding": [
                            {
                                "system": "http://example.org/service-category",
                                "code": "gp",
                                "display": "General Practice"
                            }
                        ]
                    }
                ],
                "serviceType": [
                    {
                        "coding": [
                            {
                                "code": "52",
                                "display": "General Discussion"
                            }
                        ]
                    }
                ],
                "specialty": [
                    {
                        "coding": [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "394814009",
                                "display": "General practice"
                            }
                        ]
                    }
                ],
                "appointmentType": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/v2-0276",
                            "code": "FOLLOWUP",
                            "display": "A follow up visit from a previous appointment"
                        }
                    ]
                },
                "priority": 5,
                "description": "Discussion on the results of your recent MRI",
                "start": "2013-12-10T09:00:00Z",
                "end": "2013-12-10T11:00:00Z",
                "created": "2013-10-10",
                "comment": "Further expand on the results of the MRI and determine the next actions that may be appropriate.",
                "participant": [
                    {
                        "actor": {
                            "reference": "Patient/2078",
                            "display": "Peter James Chalmers"
                        },
                        "required": "required",
                        "status": "accepted"
                    },
                    {
                        "type": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
                                        "code": "ATND"
                                    }
                                ]
                            }
                        ],
                        "actor": {
                            "reference": "Practitioner/2079",
                            "display": "Dr Adam Careful"
                        },
                        "required": "required",
                        "status": "accepted"
                    },
                    {
                        "actor": {
                            "reference": "Location/2074",
                            "display": "South Wing, second floor"
                        },
                        "required": "required",
                        "status": "accepted"
                    }
                ]
            },
            "search": {
                "mode": "match"
            }
        }
    ]
}
```
:::
::::