FAfactorialhr
Timeoff > Leave

Reads all Leaves

Changed on

Reads all Leaves

get/api/2026-10-01/resources/timeoff/leaves

Request

  • Base URL
    https://api.factorialhr.com
  • URL
    https://api.factorialhr.com/api/2026-10-01/resources/timeoff/leaves
  • Auth
    • OAuth 2
      Authorization code: https://id.factorialhr.com/oauth/authorize
      Token URL: https://id.factorialhr.com/api/oauth/token scopes: time_off
    • or API key in header x-api-key

Query parameters

ids[]string[]

Return only the leaves with these ids.

[
  "1"
]
employee_ids[]string[]

Return only the leaves of these employees.

[
  "1"
]
leave_type_id[]string[]

Return only the leaves of these leave types. Despite the singular name it takes a list.

[
  "36"
]
tostring

Return only the leaves that had already started by this date (start date on or before it). Usable on its own; pair it with from for a window.

Example:2028-09-30
fromstring

Return only the leaves that had not finished before this date, meaning they end on or after it or have no end date at all. Usable on its own; pair it with to for a window.

Example:2028-09-01
only_activeboolean

Retrieve only active leaves

include_deleted_leavesboolean required

Whether to include deleted leaves (not included by default if not specified)

Example:true
approvedboolean

Set to true for leaves that were approved, false for leaves that were rejected. Leave it unset for every leave whatever its decision. Combining approved: true with include_pending: true returns approved and still-pending leaves together.

Example:true
include_pendingboolean

Set to true to include leaves still awaiting a decision. On its own it returns ONLY the pending ones; alongside approved: true it returns approved and pending together.

Example:true
include_leave_typeboolean

Retrieve leave types

include_durationboolean

Retrieve leave duration

Example:true
include_duration_by_dayboolean

Retrieve the per-day breakdown of the leave's duration (duration_by_day_attributes)

type_is_workableboolean

Set to true for leaves whose leave type counts as worked time, false for those that do not. Leave it unset to get both.

type_is_payableboolean

Set to true for leaves whose leave type is paid, false for unpaid ones. Leave it unset to get both.

forced_finish_onstring

Caps the per-day duration walk at this date. For endless leaves (finish_on = nil) it pins the walk end; for closed leaves whose finish_on sits past this date it truncates the walk. Never extends a leave past its real finish_on. Must fall inside the read window (from/to or overlaps_range_from/overlaps_range_to).

Example:2028-09-30

Response

OK

Example response

{
  "data": [
    {
      "id": "1",
      "company_id": "1",
      "employee_id": "1",
      "start_on": "2028-09-05",
      "finish_on": "2028-09-05",
      "description": "Annual family vacation",
      "reason": "Medical appointment",
      "leave_type_id": "36",
      "approved": true,
      "employee_full_name": "Bob The Boss",
      "start_time": "09:00",
      "hours_amount_in_cents": 800,
      "updated_at": "2028-03-11T17:03:12.000Z",
      "created_at": "2028-03-11T17:03:12.000Z",
      "deleted_at": "2028-03-11T17:03:12.000Z",
      "days_taken": 1
    }
  ]
}

Changes