Availability API

Query available slots, set schedules, and create date overrides.

GET /availabilityGET /availability/checkPOST /availability/schedulesPOST /availability/overridesGET /availability/overridesDELETE /availability/overrides/:id

GET/availability

Get available time slots for a specific event type within a date range.

Query Parameters:

Param	Required	Description
`eventTypeId`	Yes	Event type to check
`start`	Yes	Start date (YYYY-MM-DD)
`end`	Yes	End date (YYYY-MM-DD)
`timezone`	No	Return slots in this timezone

GET /availability?eventTypeId=evt_abc123&start=2024-01-15&end=2024-01-31&timezone=America/New_York

// Response (200 OK)
{
  "slots": [
    {
      "start": "2024-01-15T14:00:00Z",
      "end": "2024-01-15T14:30:00Z",
      "hostUserId": "usr_abc123"
    },
    {
      "start": "2024-01-15T15:00:00Z",
      "end": "2024-01-15T15:30:00Z",
      "hostUserId": "usr_abc123"
    }
  ],
  "timezone": "America/New_York"
}

GET/availability/check

Check if a specific time slot is available for booking. Useful for real-time validation.

Query Parameters:

Param	Required	Description
`eventTypeId`	Yes	Event type ID
`startTime`	Yes	ISO 8601 start time
`timezone`	No	Default: UTC

GET /availability/check?eventTypeId=evt_123&startTime=2024-01-15T14:00:00Z&timezone=UTC

// Response (200 OK)
{
  "available": true
}

// Response (200 OK - Unavailable)
{
  "available": false,
  "reason": "Time slot is not available"
}

POST/availability/schedules

Set the recurring weekly availability schedule.

Day of Week Values:

0 = Sunday1 = Monday2 = Tuesday3 = Wednesday4 = Thursday5 = Friday6 = Saturday

// Request
{
  "timezone": "America/New_York",
  "schedules": [
    {
      "dayOfWeek": 1,
      "slots": [
        { "startTime": "09:00", "endTime": "12:00" },
        { "startTime": "13:00", "endTime": "17:00" }
      ]
    },
    {
      "dayOfWeek": 2,
      "slots": [
        { "startTime": "09:00", "endTime": "17:00" }
      ]
    }
  ]
}

// Response (200 OK)
{
  "schedule": {
    "id": "sch_abc123",
    "timezone": "America/New_York",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

POST/availability/overrides

Create date-specific availability rules that override your weekly schedule.

🚫 Mark Unavailable

{
  "date": "2024-01-20",
  "type": "unavailable",
  "reason": "Out of office"
}

⚡ Custom Hours

{
  "date": "2024-01-21",
  "type": "custom",
  "slots": [
    { "startTime": "10:00", "endTime": "14:00" }
  ]
}

GET/availability/overrides

List all date overrides within a date range.

Required params: startDate, endDate

DELETE/availability/overrides/:id

Remove a date override. Your regular weekly schedule will apply again for that date.

INFOHow Availability is Calculated

Availability slots are generated based on the Event Type configuration. The following settings (defined in the Event Type) impact which slots are returned:

bufferBeforeMinutesTime added before each slot.
bufferAfterMinutesTime added after each slot.
minimumNoticeHoursBlocks slots too close to the current time.
bookingWindowDaysMaximum days in the future to show availability.
maxBookingsPerDayLimits total bookings for the host/event type per day.
schedulingTyperound_robin rotates hosts, while collective requires all hosts to be free.

Bookings API

Team API