Leave balances

What leave a person has, by leave type. Worked out when you ask, so there is nothing to page through.

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

Fields

LeaveBalance fields
Field	Type	Access	Meaning
employee_id	string	Read-only	Whose balance it is.
employment_id	string	Read-only	Their employment.
leave_type	string	Read-only	The leave type's key.
balance_hours	number, may be null	Read-only	Hours accrued and not yet taken. Empty when the balance is kept in the payroll system and could not be read, or has not been set up.
available_hours	number, may be null	Read-only	Hours the person can still request, after pending and approved leave.
unlimited	boolean	Read-only	True when the leave type has no limit.
source	string	Read-only	shiftly when Shiftly keeps the balance, otherwise the payroll system that does.
as_at	timestamp	Read-only	When the balance was worked out.

Operations

List one person's leave balances

GET/v1/leave-balances

Permission: leave:read

Query parameters
Parameter	Type		Meaning
employee_id	string	Required	Only this person.

200 response

{
  "data": [
    {
      "employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "employment_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "leave_type": "text",
      "balance_hours": 1.5,
      "available_hours": 1.5,
      "unlimited": true,
      "source": "text",
      "as_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.