Leave requests

Requests for leave. A request your app submits is pending until a manager decides it in Shiftly. Dates are calendar days at the business's first location.

Needs one of the leave:read or leave:write permissions, depending on the operation. The business sees it as "Leave and balances".

Fields

LeaveRequest fields
Field	Type	Access	Meaning
id	string	Read-only	The leave request.
employee_id	string	Writable	Whose leave it is.
employment_id	string	Read-only	Their employment.
leave_type	string	Writable	The leave type's key, from the leave types list. Private kinds of leave, such as family and domestic violence leave, always show as PRIVATE.
start_date	date	Writable	First day of leave.
end_date	date	Writable	Last day of leave.
start_time	timestamp, may be null	Read-only	Start, for part-day leave.
end_time	timestamp, may be null	Read-only	End, for part-day leave.
hours_per_day	array of object	Read-only	Hours of leave on each day. Worked out by Shiftly.
total_hours	number	Read-only	Total hours of leave.
status	"pending", "approved", "declined", "cancelled"	Read-only	pending until a manager decides it in Shiftly.
note	string, may be null	Writable	The note on the request. May contain personal information. Always empty for private kinds of leave.
created_by_app	boolean	Read-only	True when your app submitted this request.
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 requests

GET/v1/leave-requests

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.
employee_id	string	Optional	Only this person.
status	"pending", "approved", "declined", "cancelled"	Optional	Only records in this status.

200 response

{
  "data": [
    {
      "id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "employment_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "leave_type": "text",
      "start_date": "2026-10-06",
      "end_date": "2026-10-06",
      "start_time": "2026-10-06T09:00:00+11:00",
      "end_time": "2026-10-06T09:00:00+11:00",
      "hours_per_day": [],
      "total_hours": 1.5,
      "status": "pending",
      "note": "text",
      "created_by_app": true,
      "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.

Submit a pending leave request for a person

POST/v1/leave-requests

Permission: leave:write

Request body
Field	Type	Required	Meaning
employee_id	string	Required	Whose leave it is.
leave_type	string	Required	The leave type's key, from the leave types list. Private kinds of leave, such as family and domestic violence leave, always show as PRIVATE.
start_date	date	Required	First day of leave.
end_date	date	Required	Last day of leave.
note	string, may be null	Optional	The note on the request. May contain personal information. Always empty for private kinds of leave.

Request body

{
  "employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "leave_type": "text",
  "start_date": "2026-10-06",
  "end_date": "2026-10-06",
  "note": "text"
}

201 response

{
  "id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "employment_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "leave_type": "text",
  "start_date": "2026-10-06",
  "end_date": "2026-10-06",
  "start_time": "2026-10-06T09:00:00+11:00",
  "end_time": "2026-10-06T09:00:00+11:00",
  "hours_per_day": [
    {
      "date": "2026-10-06",
      "hours": 1.5
    }
  ],
  "total_hours": 1.5,
  "status": "pending",
  "note": "text",
  "created_by_app": true,
  "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.
409	The error's code is conflict, idempotency_key_reused or request_in_progress. The Errors page describes each code.
422	A field is wrong. The field property names it.
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 request

GET/v1/leave-requests/{id}

Permission: leave:read

200 response

{
  "id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "employment_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "leave_type": "text",
  "start_date": "2026-10-06",
  "end_date": "2026-10-06",
  "start_time": "2026-10-06T09:00:00+11:00",
  "end_time": "2026-10-06T09:00:00+11:00",
  "hours_per_day": [
    {
      "date": "2026-10-06",
      "hours": 1.5
    }
  ],
  "total_hours": 1.5,
  "status": "pending",
  "note": "text",
  "created_by_app": true,
  "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.

Cancel a pending leave request your app submitted

POST/v1/leave-requests/{id}/cancel

Permission: leave:write

200 response

{
  "id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "employment_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "leave_type": "text",
  "start_date": "2026-10-06",
  "end_date": "2026-10-06",
  "start_time": "2026-10-06T09:00:00+11:00",
  "end_time": "2026-10-06T09:00:00+11:00",
  "hours_per_day": [
    {
      "date": "2026-10-06",
      "hours": 1.5
    }
  ],
  "total_hours": 1.5,
  "status": "pending",
  "note": "text",
  "created_by_app": true,
  "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.
409	The error's code is conflict, leave_not_pending, idempotency_key_reused or request_in_progress. The Errors page describes each code.
422	A field is wrong. The field property names it.
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.

Not available to partner apps

POST /v1/leave-requests/{id}/approve
Leave is approved and declined in Shiftly, not by partner apps.
POST /v1/leave-requests/{id}/decline
Leave is approved and declined in Shiftly, not by partner apps.