Sign in

v1

latestOpenAPI 3.1.02026-07-242735131.1 MB
Time Off

List Time Off

Lists all Time Off records.

Scopes

CategoryRead only ScopeWrite only Scope (read access implicit)
Manage timeoffs (time_and_attendance)View timeoffs (timeoff:read)Manage timeoffs (timeoff:write)
get/v1/timeoff

Query parameters

employment_idstring

Only show time off for a specific employment

timeoff_type'time_off' | 'sick_leave' | 'public_holiday' | 'unpaid_leave' | 'extended_leave' | 'in_lieu_time' | 'maternity_leave' | 'paternity_leave' | 'parental_leave' | 'bereavement' | 'military_leave' | 'other' | 'paid_time_off' | 'custom_company_leave' | 'rtt' | 'casual_leave' | 'rol' | 'ex_festivita'
Example:sick_leave

Filter time off by its type

status'approved' | 'cancelled' | 'declined' | 'requested' | 'taken' | 'cancel_requested'

The current status of a time off request.

  • requested: The employee has submitted a time off request and it is awaiting approval.
  • approved: The time off request has been approved by a manager.
  • cancelled: The time off request was cancelled by the employee or an admin.
  • declined: The time off request was declined by a manager.
  • taken: The approved time off has been taken (the dates have passed).
  • cancel_requested: The employee has requested cancellation of a previously approved time off, pending manager approval.
Example:requested

Filter time off by its status

start_datestring date

UTC date in ISO 8601 format

Example:2021-07-01

ISO 8601 date. When combined with end_date, returns all time off records that overlap the [start_date, end_date] window — including records that only partially overlap at either boundary. When used alone, returns records whose start_date is on or after this date.

end_datestring date

UTC date in ISO 8601 format

Example:2021-07-01

ISO 8601 date. When combined with start_date, returns all time off records that overlap the [start_date, end_date] window — including records that only partially overlap at either boundary. When used alone, returns records whose end_date is on or before this date.

order'asc' | 'desc'

Sort order

sort_by'timeoff_type' | 'status'

Field to sort by

pageinteger

Starts fetching records after the given page

page_sizeinteger

Number of items per page

Headers

Authorizationstring required

Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.

The refresh token needs to have been obtained through the Authorization Code flow.

Response

Success

Example response

{
  "current_page": 1,
  "timeoffs": [
    {
      "automatic": false,
      "document": {
        "id": "9880b711-file-id-ecf8f551bd78",
        "inserted_at": "2021-07-15T18:18:17Z",
        "name": "id.pdf",
        "sub_type": "personal_id",
        "type": "id"
      },
      "employment_id": "5e55386e-4f4f-4def-92f4-bdc19a5ce77d",
      "end_date": "2021-12-21",
      "id": "0073fcb5-b669-4e4a-b963-2a47744e75a1",
      "leave_policy": {
        "leave_policy_variant_slug": "663e0b79-c893-45ff-a1b2-f6dcabc098b5",
        "leave_type": "sick_leave",
        "name": "Self-Care"
      },
      "notes": "Some notes",
      "start_date": "2021-12-20",
      "status": "approved",
      "timeoff_days": [
        {
          "day": "2021-12-20",
          "hours": 8,
          "minutes": 480
        },
        {
          "day": "2021-12-21",
          "hours": 8,
          "minutes": 480
        }
      ],
      "timeoff_type": "paid_time_off",
      "timezone": "Asia/Kolkata",
      "total_minutes": 960
    }
  ],
  "total_count": 1,
  "total_pages": 1
}