List Time Off

Changed on Sep 3, 2026

Lists all Time Off records.

Authentication

This endpoint accepts any one of the following token types:

Company-scoped access token (OAuth2AuthorizationCode) — obtained through the Authorization Code flow or the Refresh Token flow. See Authentication for partners.
Customer API token (CustomerAPIToken) — generated by the customer on their Integration Settings page. See Authorization for customers.

Scopes

Category	Read only Scope	Write only Scope (read access implicit)
Manage timeoffs (time_and_attendance)	View timeoffs (timeoff:read)	Manage timeoffs (timeoff:write)

get/v1/timeoff

Request

Base URL: https://gateway.remote.com
URL: https://gateway.remote.com/v1/timeoff
Auth: HTTP bearer and OAuth 2 (authorization code, authorization URL /auth/oauth2/authorize, token URL /auth/oauth2/token, scopes: https://gateway.remote.com/company.manage, timeoff:read, timeoff:write, time_and_attendance, all:write, all:read)

Query parameters

employment_idstring

Only show time off for a specific employment

The type of leave a time off record or leave policy represents.

Responses may return any of these values. The set is a superset of the values accepted when creating a time off record (see TimeoffType): employments on the newer leave-type model can hold leave types that are not bookable by name.

Example:sick_leave

Filter time off by its type. Accepts every value a time off record may carry.

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
}

Changes

Sep 3, 2026f85250f1f879 Revision changes
- warning
  added the new adoption enum value to the //// response property for the response status
- warning
  added the new adoption enum value to the /// response property for the response status
- warning
  added the new adv enum value to the //// response property for the response status
- warning
  added the new adv enum value to the /// response property for the response status
- warning
  added the new blood_donation enum value to the //// response property for the response status
- warning
  added the new blood_donation enum value to the /// response property for the response status
- warning
  added the new breastfeeding enum value to the //// response property for the response status
- warning
  added the new breastfeeding enum value to the /// response property for the response status
- warning
  added the new business_trip_eu enum value to the //// response property for the response status
- warning
  added the new business_trip_eu enum value to the /// response property for the response status
- warning
  added the new business_trip_non_eu enum value to the //// response property for the response status
- warning
  added the new business_trip_non_eu enum value to the /// response property for the response status
- warning
  added the new career enum value to the //// response property for the response status
- warning
  added the new career enum value to the /// response property for the response status
- warning
  added the new caregiver enum value to the //// response property for the response status
- warning
  added the new caregiver enum value to the /// response property for the response status
- warning
  added the new celebration enum value to the //// response property for the response status
- warning
  added the new celebration enum value to the /// response property for the response status
- warning
  added the new civic_duty enum value to the //// response property for the response status
- warning
  added the new civic_duty enum value to the /// response property for the response status
- warning
  added the new exam enum value to the //// response property for the response status
- warning
  added the new exam enum value to the /// response property for the response status
- warning
  added the new force_majeure enum value to the //// response property for the response status
- warning
  added the new force_majeure enum value to the /// response property for the response status
- warning
  added the new health_day enum value to the //// response property for the response status
- warning
  added the new health_day enum value to the /// response property for the response status
- warning
  added the new marriage enum value to the //// response property for the response status
- warning
  added the new marriage enum value to the /// response property for the response status
- warning
  added the new marriage_child enum value to the //// response property for the response status
- warning
  added the new marriage_child enum value to the /// response property for the response status
- warning
  added the new maternity_paid enum value to the //// response property for the response status
- warning
  added the new maternity_paid enum value to the /// response property for the response status
- warning
  added the new maternity_unpaid enum value to the //// response property for the response status
- warning
  added the new maternity_unpaid enum value to the /// response property for the response status
- warning
  added the new medical_visits enum value to the //// response property for the response status
- warning
  added the new medical_visits enum value to the /// response property for the response status
- warning
  added the new monkhood enum value to the //// response property for the response status
- warning
  added the new monkhood enum value to the /// response property for the response status
- warning
  added the new paternity_paid enum value to the //// response property for the response status
- warning
  added the new paternity_paid enum value to the /// response property for the response status
- warning
  added the new paternity_unpaid enum value to the //// response property for the response status
- warning
  added the new paternity_unpaid enum value to the /// response property for the response status
- warning
  added the new pregnancy_leave enum value to the //// response property for the response status
- warning
  added the new pregnancy_leave enum value to the /// response property for the response status
- warning
  added the new public_duties enum value to the //// response property for the response status
- warning
  added the new public_duties enum value to the /// response property for the response status
- warning
  added the new special enum value to the //// response property for the response status
- warning
  added the new special enum value to the /// response property for the response status
- warning
  added the new sterilization enum value to the //// response property for the response status
- warning
  added the new sterilization enum value to the /// response property for the response status
- warning
  added the new study enum value to the //// response property for the response status
- warning
  added the new study enum value to the /// response property for the response status
- warning
  added the new sustainable_employability enum value to the //// response property for the response status
- warning
  added the new sustainable_employability enum value to the /// response property for the response status
- warning
  added the new training enum value to the //// response property for the response status
- warning
  added the new training enum value to the /// response property for the response status
- warning
  added the new transfer enum value to the //// response property for the response status
- warning
  added the new transfer enum value to the /// response property for the response status
- warning
  added the new voluntary enum value to the //// response property for the response status
- warning
  added the new voluntary enum value to the /// response property for the response status
- info
  added the new enum value adoption to the query request parameter timeoff_type
- info
  added the new enum value adv to the query request parameter timeoff_type
- info
  added the new enum value blood_donation to the query request parameter timeoff_type
- info
  added the new enum value breastfeeding to the query request parameter timeoff_type
- info
  added the new enum value business_trip_eu to the query request parameter timeoff_type
- info
  added the new enum value business_trip_non_eu to the query request parameter timeoff_type
- info
  added the new enum value career to the query request parameter timeoff_type
- info
  added the new enum value caregiver to the query request parameter timeoff_type
- info
  added the new enum value celebration to the query request parameter timeoff_type
- info
  added the new enum value civic_duty to the query request parameter timeoff_type
- info
  added the new enum value exam to the query request parameter timeoff_type
- info
  added the new enum value force_majeure to the query request parameter timeoff_type
- info
  added the new enum value health_day to the query request parameter timeoff_type
- info
  added the new enum value marriage to the query request parameter timeoff_type
- info
  added the new enum value marriage_child to the query request parameter timeoff_type
- info
  added the new enum value maternity_paid to the query request parameter timeoff_type
- info
  added the new enum value maternity_unpaid to the query request parameter timeoff_type
- info
  added the new enum value medical_visits to the query request parameter timeoff_type
- info
  added the new enum value monkhood to the query request parameter timeoff_type
- info
  added the new enum value paternity_paid to the query request parameter timeoff_type
- info
  added the new enum value paternity_unpaid to the query request parameter timeoff_type
- info
  added the new enum value pregnancy_leave to the query request parameter timeoff_type
- info
  added the new enum value public_duties to the query request parameter timeoff_type
- info
  added the new enum value special to the query request parameter timeoff_type
- info
  added the new enum value sterilization to the query request parameter timeoff_type
- info
  added the new enum value study to the query request parameter timeoff_type
- info
  added the new enum value sustainable_employability to the query request parameter timeoff_type
- info
  added the new enum value training to the query request parameter timeoff_type
- info
  added the new enum value transfer to the query request parameter timeoff_type
- info
  added the new enum value voluntary to the query request parameter timeoff_type
Jul 9, 202609e853f2b604 Revision changes
- info
  added the required property ///// to the response with the status
- info
  added the required property /// to the response with the status

Operation history (3 revisions)