Unavailability blocks (one-off)
List, create, replace, and delete stored out-of-office blocks and fetch the merged unavailability calendar for a location, resource, or service.
When to use
- Show a calendar-style grid of blocked intervals (weekly hours, recurring rules, appointments, holidays, stored OOF blocks) for integrator-built UIs.
- Create or delete stored out-of-office (OOF) blocks that persist on the entity until removed.
- Replace all OOF blocks for one entity in one call (
setUnavailabilityBlocks).
Protected routes require dashboard auth (Authorization + x-api-key) like other /v3/* endpoints.
Endpoints (/v3/unavailability)
/v3/unavailability)Typical operations (full request bodies and schemas are in the API reference):
| Method | Path | Purpose |
|---|---|---|
GET | /v3/unavailability | Calendar view: one row per concrete interval for the scope and date range; rows include source, entity_type, entity_id, times, and reasons |
GET | /v3/unavailability/calendar | Deprecated — same response as GET /v3/unavailability; use the canonical path (changelog) |
GET | /v3/unavailability/blocks | List stored OOF blocks for one location, resource, or service (required date overlap + scope query params) |
POST | /v3/unavailability | Create one or more stored blocks (JSON array body) |
POST | /v3/unavailability/setUnavailabilityBlocks | Replace all OOF blocks for a single location, resource, or service |
DELETE | /v3/unavailability/blocks/:id | Delete a stored OOF block by UUID |
Calendar query (GET /v3/unavailability)
GET /v3/unavailability)Query parameters:
startDate,endDate— required ISO 8601 range for the calendar window.- Scope — at least one of
LocationIds,ResourceIds, orServiceId(arrays repeat for multiple IDs where applicable). ServiceIdis optional when locations or resources narrow scope.
Responses are not merged across sources: each row is one interval with metadata so clients can badge by provenance. GET /v3/unavailability/calendar is deprecated but returns the same payload — migrate to GET /v3/unavailability.
Calendar rows use snake_case fields such as start_time, end_time, reason, reason_type, source, entity_type, and entity_id.
Stored blocks (GET/POST/DELETE)
GET/POST/DELETE)List blocks (GET /v3/unavailability/blocks)
GET /v3/unavailability/blocks)Query: required startDate and endDate (ISO 8601). Exactly one of LocationId, ResourceId, or ServiceId scopes the list.
Create blocks (POST /v3/unavailability)
POST /v3/unavailability)Body: a JSON array of objects. Each object requires:
startTime,endTime— ISO 8601 timestamps with timezone (suffixZor numeric offset such as-05:00).- At least one of
LocationId,ResourceId,ServiceIdper block. - Optional
reason(string).
Replace all OOF blocks (POST /v3/unavailability/setUnavailabilityBlocks)
POST /v3/unavailability/setUnavailabilityBlocks)Body: exactly one of LocationId, ResourceId, ServiceId, plus optional blocks array. Each block in blocks requires startTime / endTime with timezone and optional reason. An empty blocks array clears stored OOF blocks for that entity.
Delete one block (DELETE /v3/unavailability/blocks/:id)
DELETE /v3/unavailability/blocks/:id)Path: block UUID. Removes a stored OOF row (company ownership enforced). Appointment-linked or native flows may require different APIs — use this for persisted OOF blocks only.
Related documentation
Updated 1 day ago