Availability Guide

When to Request Availability

When building booking flows that need to display open time slots before creating an appointment.
To confirm whether a group of resources is jointly available for the same appointment (roundRobin=NONE).
To surface the next open time for a service (firstAvailable=true).

Availability calculations are intensive. Narrow your requests to only the dates, locations, services, and resources that matter for the user to keep responses fast.

Required Context

Authentication: All availability requests require a valid API key with access to the requested company.
Date range: Define a finite window with startDate and endDate. Broad ranges increase response time.
Service setup: The service must have a duration. Optional fields such as durationSelect, durationInterval, and padding influence the shape of the returned slots.

Query Parameters

Parameter	Required	Description
`startDate`	✔︎	ISO 8601 timestamp or `YYYY-MM-DD`. Date-only inputs are sanitized to midnight in the requested timezone (defaults to UTC).
`endDate`	✔︎	ISO 8601 timestamp or `YYYY-MM-DD`. Date-only inputs are sanitized to 23:59:59 in the requested timezone. Must be on or after `startDate`.
`LocationId`	✔︎	UUID of the location you want to check.
`ServiceId`	✔︎	UUID of the service. The service’s duration, padding, and interval configuration drive slot generation.
`ResourceIds`	–	Target specific resources. Accepts a repeated param (`ResourceIds=id1&ResourceIds=id2`). If omitted, availability is calculated using all resources linked to the service at the location.
`roundRobin`	–	Controls how resources are selected. `BALANCED` picks the resource with the fewest appointments in the search window. `RANDOM` (default) chooses any available resource. `NONE` requires every requested resource to be available for the same slot.
`syncExternal`	–	When `true`, Connected Google or Outlook calendars are synced before slots are calculated so external events block availability. Adds latency; only enable when you must reflect immediate external updates.
`timezone`	–	IANA timezone (e.g., `America/New_York`). Results are returned in this timezone instead of UTC.
`overrideDuration`	–	Override the service duration for this request. The value must be divisible by the service’s `durationInterval`, and the service must allow duration selection.
`interval`	–	Controls how often candidate start times are generated. Defaults to the service duration (or override). Set it lower for rolling availability or higher to space out slots—for example, a 30-minute service with `interval=60` returns hourly start times while the appointment still lasts 30 minutes.
`firstAvailable`	–	When `true`, the response stops after the first qualifying slot. Useful for “Next available” experiences.

Note: Adjusting interval changes the stepping between slot start times only—it never alters the actual appointment duration returned by the service settings.

How Slots Are Built

At a high level, the system:

Filters resources allowed for the service/location combination (or the ones you supplied).
Considers weekly schedules, recurring blocks, single allocations, and existing appointments to identify open windows.
Applies service duration, padding, and interval rules to generate bookable slots.
Optionally randomizes or balances resource selection based on roundRobin.

No internal scheduling logic is exposed in the response, but every slot returned respects these rules.

Response Snapshot

Successful responses include both a flat list of time slots and a day-by-day view:

{
  "ServiceId": "645afc52-8c92-4ba2-8047-de56f8783f99",
  "availableTimes": [
    {
      "start_time": "2025-02-14T14:00:00-05:00",
      "end_time": "2025-02-14T14:30:00-05:00",
      "LocationId": "fd9a18bb-8e9f-45be-be3d-3aa1b6aa0644",
      "ResourceIds": ["1e7962b6-097c-433e-a1a7-89ac48632fda"]
    }
  ],
  "availableDays": {
    "2025-02-14": [
      {
        "start_time": "2025-02-14T14:00:00-05:00",
        "end_time": "2025-02-14T14:30:00-05:00",
        "ResourceIds": ["1e7962b6-097c-433e-a1a7-89ac48632fda"]
      }
    ],
    "2025-02-15": []
  }
}

Slots are returned chronologically. Days without availability are present with an empty array so calendars can still render the date.

Usage Patterns

Single-Day Search for a Known Resource

GET /v3/availability?startDate=2025-03-21&endDate=2025-03-21&LocationId=<loc>&ServiceId=<svc>&ResourceIds=<resource>

Use this for lightweight checks (for example, a detail page that only shows today’s remaining capacity).

Rolling Availability Across Multiple Days

GET /v3/availability?startDate=2025-03-21T00:00:00Z&endDate=2025-03-24T23:59:59Z&LocationId=<loc>&ServiceId=<svc>&roundRobin=BALANCED

Specify a timezone if you prefer results localized for your client. Keep the window tight; seven days or smaller generally yields responsive results.

Coordinated Resources (`roundRobin=NONE`)

To book multi-resource appointments (for example, a practitioner and a room), set roundRobin=NONE and supply every required resource ID. A slot only surfaces when each resource is free for the full duration.

First Available Shortcut

GET /v3/availability?startDate=now&endDate=now+7d&LocationId=<loc>&ServiceId=<svc>&firstAvailable=true

The response contains a single time slot. Combine with syncExternal=true when you must reflect up-to-the-minute calendar changes.

Working with Timezones

Include timezone to translate availableTimes and availableDays into the user’s local time.
If omitted, times are returned as UTC. Date-only inputs default to midnight or 23:59:59 in the selected timezone before conversion to UTC for processing.
Always store the original timezone in your client if you need to compare with local system times.

Performance & Caching Tips

Results are cached for one hour per unique query. Repeating the same call within that period returns the cached payload instantly.
Cache invalidates automatically when new unavailability blocks are inserted (for example, after syncing external calendars or creating appointments).
Use the narrowest date range possible. Multi-week windows or large resource sets increase processing time.
Only enable syncExternal when you must capture calendar updates immediately; otherwise rely on the background sync cadence to keep external events current.

Troubleshooting

Missing availability: Confirm the service has a duration and that the requested resources are linked to the service at the location.
Empty days on multi-day searches: We intentionally return empty arrays so you can display disabled dates on calendars.
overrideDuration rejected: Ensure the service allows selectable durations and the override value is a multiple of durationInterval.
Timezone confusion: Double-check the timezone parameter and remember responses are converted after all calculations.

With these practices, you can design booking experiences that surface relevant availability quickly while keeping server load manageable.