Availability

The Availability API provides real-time booking slot queries. It accounts for clinician sessions, existing bookings, buffer times, holds, blocks, minimum notice periods, and maximum advance booking rules.

Endpoints

Method	Endpoint	Description
`GET`	`/availability`	List available slots for a date range
`GET`	`/availability/next`	Find the next available slot
`POST`	`/availability/verify`	Verify a specific slot is still available

Availability is computed in real-time — it is not a stored resource. Slots can be taken between query and booking, so always verify before confirming.

List Available Slots

GET /availability

Returns all available booking slots for a given date range and appointment template. Maximum date range is 14 days.

Query Parameters

Parameter	Type	Required	Description
`date_from`	date	Yes	Start date (`YYYY-MM-DD`)
`date_to`	date	Yes	End date (`YYYY-MM-DD`), max 14 days from `date_from`
`appointment_template_id`	string	Yes	The appointment type to check availability for
`clinician_profile_id`	uuid	No	Filter to a specific clinician
`location_id`	uuid	No	Filter to a specific location

Example Request

curl -H "Authorization: Bearer pk_live_xxx" \
  "https://api.jumpehr.com/api-v1/availability?date_from=2024-07-01&date_to=2024-07-07&appointment_template_id=apt_type_gp_standard"

Example Response

{
  "data": {
    "slots": [
      {
        "start_time": "2024-07-01T09:00:00Z",
        "end_time": "2024-07-01T09:15:00Z",
        "clinician_profile_id": "abc-123",
        "clinician_name": "Dr Sarah Johnson",
        "location_id": "loc-456",
        "appointment_template_id": "apt_type_gp_standard",
        "is_available": true
      }
    ],
    "date_range": {
      "from": "2024-07-01",
      "to": "2024-07-07"
    }
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Find Next Available

GET /availability/next

Lightweight endpoint that finds the next available slot within 30 days. Returns null data if nothing is available.

Query Parameters

Parameter	Type	Required	Description
`appointment_template_id`	string	Yes	The appointment type to check
`clinician_profile_id`	uuid	No	Filter to a specific clinician
`location_id`	uuid	No	Filter to a specific location

Example Response

{
  "data": {
    "next_available": "2024-07-01T09:00:00Z",
    "clinician_profile_id": "abc-123",
    "clinician_name": "Dr Sarah Johnson",
    "location_id": "loc-456",
    "appointment_template_id": "apt_type_gp_standard"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Verify Slot Availability

POST /availability/verify

Verify that a specific slot is still available before proceeding to payment or booking. This is the recommended step between displaying slots and creating an appointment.

Request Body

Field	Type	Required	Description
`appointment_template_id`	string	Yes	The appointment type
`start_time`	datetime	Yes	Slot start (ISO 8601)
`end_time`	datetime	Yes	Slot end (ISO 8601)
`clinician_profile_id`	uuid	No	Specific clinician
`location_id`	uuid	No	Specific location

Example Response (Available)

{
  "data": {
    "available": true,
    "start_time": "2024-07-01T09:00:00Z",
    "end_time": "2024-07-01T09:15:00Z"
  },
  "meta": { "request_id": "req_abc123" }
}

Example Response (Unavailable)

{
  "data": {
    "available": false,
    "reason": "Slot has been booked by another patient",
    "next_available": "2024-07-01T09:30:00Z"
  },
  "meta": { "request_id": "req_abc123" }
}

⚠️

The next_available suggestion is best-effort — verify it again before booking.

Questionnaire Responses Locations