Leave blackout periods

Periods when the business limits leave, such as a busy season. Dates are calendar days at the business's first location.

Needs the leave:read permission, depending on the operation. The business sees it as "Leave and balances".

Fields

LeaveBlackout fields
Field	Type	Access	Meaning
id	string	Read-only	The blackout period.
name	string	Read-only	The period's name.
start_date	date	Read-only	First day of the period.
end_date	date	Read-only	Last day of the period.
enforcement	"hard_block", "soft_warn", "informational"	Read-only	hard_block stops staff asking for these kinds of leave in Shiftly, soft_warn warns them, informational only shows the period. None of them stops a manager in Shiftly, or your app, from submitting leave.
leave_types	array of string	Read-only	The kinds of leave the period applies to, as keys from the leave types list.
reason	string, may be null	Read-only	Why the period is blocked out, as staff see it.
archived	boolean	Read-only	True when the record has been removed in Shiftly.
created_at	timestamp	Read-only	When the record was created.
updated_at	timestamp	Read-only	When the record last changed.

Operations

List leave blackout periods

GET/v1/leave-blackouts

Permission: leave:read

Query parameters
Parameter	Type		Meaning
limit	integer, default 50, up to 200	Optional	How many records per page. Up to 200.
after	string	Optional	The next_cursor from the previous page.
updated_since	timestamp	Optional	Only records changed at or after this moment. Pair it with include_archived to see removals.
include_archived	"true", "false"	Optional	Include records that have been archived.
from	date	Optional	The first day of the range, in the location's timezone. With to, at most 92 days.
to	date	Optional	The last day of the range, inclusive.

200 response

{
  "data": [
    {
      "id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "name": "text",
      "start_date": "2026-10-06",
      "end_date": "2026-10-06",
      "enforcement": "hard_block",
      "leave_types": [],
      "reason": "text",
      "archived": true,
      "created_at": "2026-10-06T09:00:00+11:00",
      "updated_at": "2026-10-06T09:00:00+11:00"
    }
  ],
  "has_more": true,
  "next_cursor": "text"
}

Refusals
Status	When
400	The error's code is invalid_request or range_too_long. The Errors page describes each code.
401	The error's code is invalid_token or token_expired. The Errors page describes each code.
403	The error's code is origin_not_allowed, permission_denied, not_available, connection_disconnected, connection_suspended or app_suspended. The Errors page describes each code.
404	There is nothing at this address, or no such record in this business.
429	Too many requests. Retry-After says when to try again.
500	Something went wrong at Shiftly. Quote the request id.
503	This environment is not set up for partner apps yet.

Get one leave blackout period

GET/v1/leave-blackouts/{id}

Permission: leave:read

200 response

{
  "id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "name": "text",
  "start_date": "2026-10-06",
  "end_date": "2026-10-06",
  "enforcement": "hard_block",
  "leave_types": [
    "text"
  ],
  "reason": "text",
  "archived": true,
  "created_at": "2026-10-06T09:00:00+11:00",
  "updated_at": "2026-10-06T09:00:00+11:00"
}

Refusals
Status	When
400	The error's code is invalid_request or range_too_long. The Errors page describes each code.
401	The error's code is invalid_token or token_expired. The Errors page describes each code.
403	The error's code is origin_not_allowed, permission_denied, not_available, connection_disconnected, connection_suspended or app_suspended. The Errors page describes each code.
404	There is nothing at this address, or no such record in this business.
429	Too many requests. Retry-After says when to try again.
500	Something went wrong at Shiftly. Quote the request id.
503	This environment is not set up for partner apps yet.