Availability Guide

When to Request Availability

When building flows that need to display open time slots before creating an appointment.
To confirm whether every resource in a fixed set can be booked together for the same slot (roundRobin=COMBINED with explicit ResourceIds).
To list every resource that could take a given slot (roundRobin=NONE), or to let the API pick one eligible resource per slot (roundRobin=RANDOM or BALANCED).
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 `ResourceIds` appear on each slot. `RANDOM` (default): exactly one resource per slot, chosen at random from resources that are eligible for that time (service duration + padding, capacity, hard blocks). `BALANCED`: one resource per slot, chosen from the same eligible pool by fewest appointments in the window (ties random). `NONE`: returns all eligible resource IDs for that slot (multiple IDs when several resources share the opening). A slot is shown if at least one candidate resource is free; booked resources are omitted from the array. `COMBINED`: only slots where every resource you pass in `ResourceIds` is jointly available; each returned slot includes the full set. COMBINED requires explicit `ResourceIds`—omitting them does not populate a default list.
`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.
Resolves which resources to consider (from ResourceIds or, for RANDOM / BALANCED / NONE, all resources linked to the service at the location when ResourceIds is omitted).
Applies roundRobin so each slot returns one randomly chosen resource, one load-balanced resource, every eligible resource, or only jointly available sets (COMBINED).

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.

With roundRobin=NONE, ResourceIds may contain more than one UUID when several resources are all free for the same start time. With roundRobin=RANDOM or BALANCED, each slot still has a single-element ResourceIds array.

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.

All eligible resources per slot (`roundRobin=NONE`)

Use NONE when the client should show who can take each time—for example, several staff share the same service and you want every free provider listed for that start time. Omitting ResourceIds uses every resource linked to the service at the location (same default candidate pool as RANDOM / BALANCED). A slot appears if at least one of those resources is available; ResourceIds on that slot lists only the ones that are still free.

Joint availability — everyone required (`roundRobin=COMBINED`)

For appointments that must include every member of a fixed set (for example, a practitioner and a room), use COMBINED and pass all required IDs in ResourceIds. A slot is returned only when each of those resources is available for the full duration (and padding). Omitting ResourceIds with COMBINED does not infer a list—you must pass the coordinated set explicitly.

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.
Appointments are stored in UTC; availability is calculated in the entity’s local timezone and converted back to the requested timezone (or UTC) in the response.
Locations define the baseline timezone. Services inherit from their location when scoped to that location. Resources inherit the timezone of the first location they are linked to unless explicitly set otherwise.
When a resource spans multiple locations, only overlapping hours return slots. For example, a resource set to America/Chicago serving both America/Los_Angeles and America/New_York locations will return fewer slots for the eastern location because only shared hours are considered.

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.