Unavailability blocks (one-off)

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)

Typical operations (full request bodies and schemas are in the API reference):

Calendar query (GET /v3/unavailability)

Query parameters:

• startDate, endDate — required ISO 8601 range for the calendar window.
• Scope — at least one of LocationIds, ResourceIds, or ServiceId (arrays repeat for multiple IDs where applicable). These IDs only match Locations, Resources, and Services owned by the authenticated company.
• ServiceId is optional when locations or resources narrow scope.
• syncExternal — optional boolean, default false. When true, connected Google or Outlook calendars are synced for the resolved resources before rows are listed. Explicit ResourceIds are limited to Resources owned by the authenticated company. This triggers just-in-time ingest only; stored external busy blocks still appear when false if they match the scope filters. Unlike GET /v3/availability, this flag does not hide stored external blocks when false. Adds latency — keep date ranges narrow.

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. Rows that come from external calendar sync may also include external_transparency, external_event_type, and external_busy (often null for non-external sources).

Stored blocks (GET/POST/DELETE)

List 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)

Body: a JSON array of objects. Each object requires:

• startTime, endTime — ISO 8601 timestamps with timezone (suffix Z or numeric offset such as -05:00).
• At least one of LocationId, ResourceId, ServiceId per block.
• Optional reason (string).

Replace all OOF blocks (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)

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

• Unavailability overview
• Recurring blocks
• Availability guide
• Unavailability glossary
• Error codes