POST/transactional-api/list-available-slots

List Available Slots

Returns bookable appointment slots from a given date, with optional filters for appointment services, types, practitioners, and sites. Results are sorted by start time. The maximum date range between fromDate and endDate is 4 weeks; if endDate is omitted, slots up to 4 weeks from fromDate are returned.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/list-available-slots' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "fromDate": "2024-07-29",
    "endDate": "2024-07-29",
    "appointmentServiceIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "appointmentTypeIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "practitionerIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "siteIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }'

Body parameters

Field	Type	Required	Description
`fromDate`	`string<date>`	Yes	Start of the search window (YYYY-MM-DD).
`endDate`	`string<date>` (nullable)	No	End of the search window (YYYY-MM-DD). Must not be before fromDate or more than 4 weeks after it. Defaults to 4 weeks from fromDate.
`appointmentServiceIds`	`array<string<uuid>>` (nullable)	No	Restrict results to these appointment service IDs.
`appointmentTypeIds`	`array<string<uuid>>` (nullable)	No	Restrict results to these appointment type IDs.
`practitionerIds`	`array<string<uuid>>` (nullable)	No	Restrict results to these practitioner IDs.
`siteIds`	`array<string<uuid>>` (nullable)	No	Restrict results to these site IDs.

Responses

200 Available slots matching the request filters.

[
  {
    "startTime": "2025-01-01T09:30:00Z",
    "endTime": "2025-01-01T09:30:00Z",
    "diaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "practitionerIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "siteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "roomId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "appointmentServiceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "appointmentTypeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "colour": "string",
    "deliveryMode": "string",
    "embargoed": false
  }
]

400 Validation error.

4 possible code values

Code	Description	When
`invalid-from-date`	The fromDate is required and must be a valid date in Y-m-d format.	fromDate missing or not a valid date in Y-m-d format
`invalid-end-date`	The endDate must be a valid date in Y-m-d format.	endDate is not a valid date in Y-m-d format (message shown), or endDate is before fromDate (message: 'The endDate must not be before fromDate.')
`max-date-range-exceeded`	Only a maximum of 4 weeks can be requested between fromDate and endDate.	endDate is more than 4 weeks after fromDate
`invalid-request`	Unrecognised field(s): <field name(s)>	the request includes a field outside the allow-list

{
  "errors": [
    {
      "code": "invalid-from-date",
      "description": "The fromDate is required and must be a valid date in Y-m-d format."
    }
  ]
}

404 A referenced appointment service or type was not found.

2 possible code values

Code	Description	When
`appointment-service-not-found`	The appointment service with the ID '3fa85f64-5717-4562-b3fc-2c963f66afa6' could not be found.	an id in appointmentServiceIds doesn't exist
`appointment-type-not-found`	Appointment type not found for id: 3fa85f64-5717-4562-b3fc-2c963f66afa6	an id in appointmentTypeIds doesn't exist

{
  "errors": [
    {
      "code": "appointment-service-not-found",
      "description": "The appointment service with the ID '3fa85f64-5717-4562-b3fc-2c963f66afa6' could not be found."
    }
  ]
}

Request​

Responses​

Request

Responses