Availability

The Availability API allows you to query available appointment slots. Use this to build booking interfaces that show when appointments can be scheduled.

Endpoints

Method	Endpoint	Description
`GET`	`/availability`	Query available slots

Required scope: read_availability

The Availability Slot Object

{
  "start_time": "2025-01-20T09:00:00Z",
  "end_time": "2025-01-20T09:30:00Z",
  "clinician_id": "cli_123e4567-e89b-12d3-a456-426614174000",
  "clinician_name": "Dr. Sarah Johnson",
  "location_id": "loc_456e7890-e89b-12d3-a456-426614174111",
  "location_name": "Central London Clinic",
  "is_remote": false
}

Attributes

Field	Type	Description
`start_time`	string	Slot start time (ISO 8601)
`end_time`	string	Slot end time (ISO 8601)
`clinician_id`	string	Available clinician ID
`clinician_name`	string	Clinician display name
`location_id`	string	Location ID
`location_name`	string	Location display name
`is_remote`	boolean	Whether slot is for video call

Query Availability

GET /availability

Query available appointment slots for a specific appointment type within a date range.

Query Parameters

Parameter	Type	Required	Description
`appointment_type_id`	string	Yes	Appointment type to check
`start_date`	string	Yes	Start of date range (YYYY-MM-DD)
`end_date`	string	Yes	End of date range (YYYY-MM-DD)
`clinician_id`	string	No	Filter by clinician
`location_id`	string	No	Filter by location
`is_remote`	boolean	No	Filter by remote/in-person

The date range is typically limited to 30 days. Contact support if you need to query longer periods.

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/availability?appointment_type_id=type_123e4567&start_date=2025-01-20&end_date=2025-01-27" \
  -H "Authorization: Bearer pk_live_your_api_key"

Response

{
  "data": [
    {
      "start_time": "2025-01-20T09:00:00Z",
      "end_time": "2025-01-20T09:30:00Z",
      "clinician_id": "cli_123e4567-e89b-12d3-a456-426614174000",
      "clinician_name": "Dr. Sarah Johnson",
      "location_id": "loc_456e7890-e89b-12d3-a456-426614174111",
      "location_name": "Central London Clinic",
      "is_remote": false
    },
    {
      "start_time": "2025-01-20T10:00:00Z",
      "end_time": "2025-01-20T10:30:00Z",
      "clinician_id": "cli_123e4567-e89b-12d3-a456-426614174000",
      "clinician_name": "Dr. Sarah Johnson",
      "location_id": "loc_456e7890-e89b-12d3-a456-426614174111",
      "location_name": "Central London Clinic",
      "is_remote": false
    },
    {
      "start_time": "2025-01-20T14:00:00Z",
      "end_time": "2025-01-20T14:30:00Z",
      "clinician_id": "cli_234f5678-e89b-12d3-a456-426614174222",
      "clinician_name": "Dr. Michael Chen",
      "location_id": null,
      "location_name": null,
      "is_remote": true
    }
  ]
}

Filter by Clinician

To show availability for a specific clinician:

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/availability?appointment_type_id=type_123e4567&start_date=2025-01-20&end_date=2025-01-27&clinician_id=cli_123e4567" \
  -H "Authorization: Bearer pk_live_your_api_key"

Filter by Location

To show availability at a specific location:

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/availability?appointment_type_id=type_123e4567&start_date=2025-01-20&end_date=2025-01-27&location_id=loc_456e7890" \
  -H "Authorization: Bearer pk_live_your_api_key"

Remote Appointments Only

To show only video/telehealth slots:

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/availability?appointment_type_id=type_123e4567&start_date=2025-01-20&end_date=2025-01-27&is_remote=true" \
  -H "Authorization: Bearer pk_live_your_api_key"

Booking Flow

Once you've found an available slot, use the Holds API to temporarily reserve it before confirming the booking.

Recommended Booking Flow

Query availability to show available slots to the user
Create a hold to temporarily reserve the chosen slot
Collect patient details while the hold is active (15 min)
Confirm the hold to convert it to an appointment

// 1. Get available slots
const availability = await fetch(
  '/api-v1/availability?appointment_type_id=type_123&start_date=2025-01-20&end_date=2025-01-27',
  { headers: { 'Authorization': 'Bearer pk_live_xxx' } }
);
 
// 2. User selects a slot, create hold
const hold = await fetch('/api-v1/holds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_live_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    appointment_type_id: 'type_123',
    clinician_id: 'cli_456',
    date: '2025-01-20',
    start_time: '09:00'
  })
});
 
// 3. Collect patient info, then confirm
const appointment = await fetch(`/api-v1/holds/${hold.id}/confirm`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_live_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patient_id: 'pat_789',
    attendee_name: 'John Smith',
    attendee_email: 'john@example.com'
  })
});

Related Resources

Holds - Reserve appointment slots
Appointments - Book appointments
Appointment Types - Service types
Clinicians - Healthcare providers
Locations - Practice locations

Locations Holds