List Appointments

Overview

This endpoints allows Patient Facing Consumer applications to retrieve a list of the patient’s appointments.

Making a request

HTTP method: GET

https://{{medicusTenant}}.{{medicusBaseURL}}/pfs-api/v1/patient/{{patientId}}/appointments

Request Headers

Header	Value	Description
`Authorization`	`Bearer [token]`	The JWT token provided by the Consumer

URL Parameters

Parameter

Description

Validation Rules

patientId

Patient ID

e.g. e9af860e-cf8e-4272-b81a-a95cc8a531f7

Mandatory

UUID

Body Parameters

Parameter

Type

Description

fromDate

date (optional)

ISO 8601 format

Only display appointments after this date

untilDate

date (optional)

ISO 8601 format

Only display appointments before this date

Example Request (No Parameters Set)

CODE

GET /pfs-api/v1/patient/e9af860e-cf8e-4272-b81a-a95cc8a531f7/appointments
Authorization: Bearer [token]

Example Request (All Optional Parameters Set)

CODE

GET /pfs-api/v1/patient/e9af860e-cf8e-4272-b81a-a95cc8a531f7/appointments
Authorization: Bearer [token]

{
    "fromDate": "2022-05-20",
    "untilDate": "2022-10-21"
}

Response Details

Specific Response Codes

HTTP Code	Error Code	Scenario
`200`		Request successful
`400`	`INVALID_DATE`	The supplied document date is in an invalid format
`400`	`INVALID_DATE_RANGE`	The specified `untilDate` cannot be before the specified `fromDate`
`404`	`PATIENT_NOT_FOUND`	No patient record exists with the specified Patient ID.

Output Fields

Field	Type	Description
`type`	enum	Possible values: `timed`
`patientSuppliedInformationForClinician`	string	The reason that the appointment was booked
`status`	enum	Possible values: `pending` `started` `seen` `rescheduled` `cancelled`
`service`	Appointment Service	The appointments service Response structure: CODE `"service": { "id": "324b5437-ef40-43f1-9ecc-26a76c1938d0", "name": "GP Surgery" }`
`startDateTime`	datetime ISO 8601 format	The date and time that the appointment starts.
`endDateTime`	datetime ISO 8601 format	The date and time that the appointment ends.
`durationMinutes`	int	The duration of the appointment slot
`deliveryMode`	Delivery Mode object	Response structure: CODE `{ "value": "face-to-face", "label": "Face-to-face" }`
`location`	Location	If set, the location of the appointment
`practitioners`	Practitioners (as array)	The associated practitioners Response structure: CODE `[ { "id": "1332aa9c-28d6-11eb-adc1-0242ac120002", "name": "Lara Lincoln" } ]`

Example Response (Successful Retrieval)

JSON

{
    "timed": [
        {
            "id": "087bce24-28d9-11eb-adc1-16097bced528",
            "type": "timed",
            "status": {
                "value": "cancelled",
                "label": "Cancelled"
            },
            "service": {
                "id": "870e9a52-28d9-11eb-adc1-01da2c9536ef",
                "name": "GP Appointments"
            },
            "startDateTime": "2023-04-14 14:00:00",
            "endDateTime": "2023-04-14 14:10:00",
            "durationMinutes": 10,
            "deliveryMode": {
                "value": "face-to-face",
                "label": "Face-to-face"
            },
            "practitioners": [
                {
                    "id": "1332aa9c-28d6-11eb-adc1-0242ac120002",
                    "name": "Lara Lincoln"
                }
            ],
            "patientSuppliedInformationForClinician": "My head hurts"
        },
        {
            "id": "13fd6428-69be-11ed-8676-0a58a9feac02",
            "type": "timed",
            "status": {
                "value": "pending",
                "label": "Pending"
            },
            "service": {
                "id": "870e9a52-28d9-11eb-adc1-01da2c9536ef",
                "name": "GP Appointments"
            },
            "startDateTime": "2022-11-22 07:10:00",
            "endDateTime": "2022-11-22 07:20:00",
            "durationMinutes": 10,
            "deliveryMode": {
                "value": "face-to-face",
                "label": "Face-to-face"
            },
            "practitioners": [
                {
                    "id": "1332aa9c-28d6-11eb-adc1-0242ac120002",
                    "name": "Lara Lincoln"
                }
            ]
        },
        {
            "id": "4e644650-69bd-11ed-bb35-0a58a9feac02",
            "type": "timed",
            "status": {
                "value": "pending",
                "label": "Pending"
            },
            "service": {
                "id": "870e9a52-28d9-11eb-adc1-01da2c9536ef",
                "name": "GP Appointments"
            },
            "startDateTime": "2022-11-22 00:10:00",
            "endDateTime": "2022-11-22 00:20:00",
            "durationMinutes": 10,
            "deliveryMode": {
                "value": "face-to-face",
                "label": "Face-to-face"
            },
            "practitioners": [
                {
                    "id": "1332aa9c-28d6-11eb-adc1-0242ac120002",
                    "name": "Lara Lincoln"
                }
            ]
        },
        {
            "id": "71f10560-6a6a-11ed-b2d8-06b89302faea",
            "type": "timed",
            "status": {
                "value": "pending",
                "label": "Pending"
            },
            "service": {
                "id": "870e9a52-28d9-11eb-adc1-01da2c9536ef",
                "name": "GP Appointments"
            },
            "startDateTime": "2022-11-22 00:20:00",
            "endDateTime": "2022-11-22 00:30:00",
            "durationMinutes": 10,
            "deliveryMode": {
                "value": "face-to-face",
                "label": "Face-to-face"
            },
            "practitioners": [
                {
                    "id": "1332aa9c-28d6-11eb-adc1-0242ac120002",
                    "name": "Lara Lincoln"
                }
            ]
        },
        {
            "id": "7532f768-69bd-11ed-850c-0ac5a9d25554",
            "type": "timed",
            "status": {
                "value": "pending",
                "label": "Pending"
            },
            "service": {
                "id": "870e9a52-28d9-11eb-adc1-01da2c9536ef",
                "name": "GP Appointments"
            },
            "startDateTime": "2022-11-22 02:40:00",
            "endDateTime": "2022-11-22 02:50:00",
            "durationMinutes": 10,
            "deliveryMode": {
                "value": "face-to-face",
                "label": "Face-to-face"
            },
            "practitioners": [
                {
                    "id": "1332aa9c-28d6-11eb-adc1-0242ac120002",
                    "name": "Lara Lincoln"
                }
            ]
        },
        {
            "id": "c53a8be7-28d9-11eb-adc1-f792c1d5e0ba",
            "type": "timed",
            "status": {
                "value": "cancelled",
                "label": "Cancelled"
            },
            "service": {
                "id": "870e9a52-28d9-11eb-adc1-01da2c9536ef",
                "name": "GP Appointments"
            },
            "startDateTime": "2023-08-28 08:00:00",
            "endDateTime": "2023-08-28 08:10:00",
            "durationMinutes": 10,
            "deliveryMode": {
                "value": "face-to-face",
                "label": "Face-to-face"
            },
            "practitioners": [
                {
                    "id": "1332aa9c-28d6-11eb-adc1-0242ac120002",
                    "name": "Lara Lincoln"
                }
            ]
        }
    ]
}