Skip to content

API Reference

Availability

Query available time slots for a service within a date range.

Get Availability

Returns available time slots grouped by date for a given service and date range.

GET /api/v1/availability

Parameters

Parameter Type Required Description
service_id uuid Yes The service to check availability for
date_from date Yes Start date (YYYY-MM-DD, must be today or later)
date_to date Yes End date (YYYY-MM-DD, must be after or equal to date_from)
staff_id uuid No Filter to a specific staff member
location_id uuid No Filter to a specific location

Constraints

  • Maximum date range: 14 days per request
  • Results are cached for 60 seconds
  • Only future slots are returned (no past times)

Example Request

curl -X GET "https://calendence.com/api/v1/availability?\
service_id=01950000-de00-4000-a000-000000000030&\
date_from=2026-03-24&\
date_to=2026-03-31" \
  -H "Authorization: Bearer cal_ses_your_session_token"

Example Response

{
  "data": {
    "2026-03-24": [
      {
        "starts_at": "2026-03-24T14:00:00+00:00",
        "ends_at": "2026-03-24T14:30:00+00:00",
        "starts_at_local": "2026-03-24T08:00:00",
        "ends_at_local": "2026-03-24T08:30:00",
        "staff": {
          "id": "01950000-de00-4000-a000-000000000011",
          "name": "Alex Rivera"
        }
      }
    ],
    "2026-03-25": [ ... ]
  },
  "meta": {
    "service_id": "01950000-de00-4000-a000-000000000030",
    "date_from": "2026-03-24",
    "date_to": "2026-03-31",
    "total_slots": 142
  }
}

Response Fields

Field Description
starts_at Slot start time in UTC (ISO 8601)
ends_at Slot end time in UTC (ISO 8601)
starts_at_local Slot start time in the business's timezone
ends_at_local Slot end time in the business's timezone
staff.id The staff member available for this slot
staff.name Staff member's display name

How Availability is Computed

The scheduling engine evaluates multiple constraints before returning a slot:

  1. Working hours — Is the staff member scheduled to work?
  2. Existing bookings — Is the time already booked?
  3. Holds — Is another client holding this slot?
  4. Buffer time — Is there enough buffer before/after?
  5. Skills — Is the staff qualified for this service?
  6. Resources — Are required bays/equipment available?
  7. Travel time — For mobile services, is there time to travel?

Only slots that pass all constraints are returned.

Pagination for Long Ranges

The 14-day limit means you'll need multiple requests to cover a full month. The booking widget handles this automatically — it requests the next 14-day window when the user navigates to a new month.