Home
Guides

Working with Time Off

Suggest Edits

Overview

The Time Off API allows users to manage employee leave requests, including listing, creating, updating, and canceling time off requests. Each request must be associated with a Time Off Type and a Status that reflects its current stage in the approval process.

Key Concepts

Time Off Types

All Time Off requests must belong to a specific type. The available types are dynamic and can change over time. The full list of types can be retrieved using the List Time Off Types endpoint.

curl --location --request GET \
-- header "Authorization: Bearer <your_token>" \
-- header "Content-Type: application/json" \
https://gateway.remote-sandbox.com/v1/timeoff/types

When called, this endpoint returns this supported time off types: paid_time_off, sick_leave, public_holiday, unpaid_leave, extended_leave, in_lieu_time, maternity_leave, paternity_leave, parental_leave, bereavement, military_leave, and other.

Time Off Statuses

A Time Off request can have one of the following statuses:

  • requested: Initial state of a request that's waiting for employer approval.
  • approved: The request has been approved by the employer.
  • taken: The approved request has been used by the employee.
  • declined: The request was declined by the employer.
  • cancel requested: Employee has requested cancellation of a previously approved request.
  • canceled: The request has been canceled.

Important Fields

approver_id

This field must match a user ID in the Remote platform with the necessary permissions to approve time off requests. You can find eligible users through the List Company Managers endpoint.

timeoff_days

This field defines the exact days and hours for the time off request.

The start_date and end_date define the duration of the leave. If the leave is for a single day, then both values should be the same. Regardless of that, the timeoff_days array must contain one entry per day, even when creating time off for a single day. For example, if the time off is required for 3 Dec, 2024, the structure of this request will be:

[
  {"day": "2024-12-03", "hours": 8}
]

Explicitly mentioning hours for these requests is a must. This number reflects the number of hours not worked on the specified day.

  • Hours should be between 0 and 8
  • For weekends or non-work days, hours should be set to 0

An example of a multi-day request:

[  
  {"day": "2024-12-03", "hours": 8},  
  {"day": "2024-12-04", "hours": 8},  
  {"day": "2024-12-05", "hours": 0},  // Saturday  
  {"day": "2024-12-06", "hours": 0},  // Sunday  
  {"day": "2024-12-07", "hours": 8}  
]

ℹ️ This system supports partial days off as well. For example, a half day off can be reflected using `"hours"

Time Off Webhooks

The Time Off endpoint supports a few webhooks, the overview of which is explained in this lifecycle diagram.

Automatic Holidays

Remote automatically books national holidays for employees based on their location.

ℹ️ Automatic holidays are always created with an approved status.

Key webhook events related to this feature include:

  • timeoff.approved: This event is triggered when an automatic holiday is created.
  • timeoff.canceled: This event is triggered when an automatic holiday is removed.
  • timeoff.date_changed: Whenever a date is recognized by Remote as a national holiday, it is automatically booked for all employees of that country. This can cause a conflict, as an employee could have previously scheduled PTO that includes this date, and now they are entitled to have it as a holiday instead of a PTO. In this case, the conflict is automatically resolved by having the time off hours of that date changed to take the holiday into consideration, which then triggers the timeoff.date_changed event.

ℹ️ In cases where a public holiday falls on a weekend, or a public holiday is not observed on the exact day, the automatic holiday feature accounts for these shifts when creating time off records. This is called an Observed holiday.

Updated 29 days ago