Working with Time Off

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.

List Time Off Types

Before creating a time off request, you need to understand the available time off types. To check the types and their details, call the List Time Off Types endpoint. The available time off types are:

paid_time_off: is the yearly paid vacation days granted to an employee.
sick_leave: is the leave granted when an employee is too sick to work. These leaves can be paid or unpaid, depending on the company policy.
public_holiday: is a nationally or regionally recognized day. These leaves are defined by the state or government.
unpaid_leave: is the type of time off where the employee is not compensated.
extended_leave: is an absence taken over a longer period of time, e.g. a few months.
in_lieu_time: is a leave granted to an employee instead of monetary compensation for work done outside of work days/hours, e.g. if an employee worked on a public holiday, they can use this type of time off to take some other day off.
maternity_leave: is the leave granted to a mother for the birth of her child.
paternity_leave: is the leave granted to a father for the birth of his child.
parental_leave: is the leave granted to parents to take care of their children.
bereavement: is the leave granted to an employee following the death of a close relative. These leaves can be paid or unpaid.
military_leave: is the leave granted to an employee to perform their military duty.
other: used for leave types that are not covered by any category mentioned above.

Create Time Off Request

You can create a new time off request using the Create Time Off endpoint. This API currently supports the creation of approved requests only. To successfully create a new request, following parameters need to be provided:

employment_id: Unique ID of the employee that's requesting time off.
start_date: The first day of leave.
end_date: The last day of leave.

ℹ️ In case of a single day leave, the start_date and end_date will be the same.
timeoff_days: It is an array of objects that defines the exact hours of the time off days. It takes,
- day field which is a UTC date in ISO 8601 format. Represents the day of leave.
- hours is an integer representing the number of hours taken off on that day. Explicitly mentioning the number of hours not worked on a specific day is mandatory. The hours should be between 0 and 8. For weekends or non-work days, hours should be set to 0.
  This array must contain one entry per day, even when creating time off for a single day. For example, if the time off is requested for 7 Dec, 2025, the structure of this request will be:
```
[
  {"day": "2024-12-03", "hours": 8}
]
```
Similarly, an example of a multi-day request looks like:

ℹ️ This system supports partial days off as well. For example, a half day off can be reflected using "hours": 4.
```
[  
  {"day": "2025-02-07", "hours": 8},  
  {"day": "2025-02-08", "hours": 0},  // Saturday  
  {"day": "2025-02-09", "hours": 0},  // Sunday  
  {"day": "2025-02-10", "hours": 4}  
]  
```
This field helps in determining the exact number of hours taken off from work so that the payroll can be adjusted accordingly.
timeoff_type: Defines the type of leave the employee is requesting. This will be a string value from any of the above mentioned list.
timezone: Defines the timezone of the dates that are mentioned in the request.
status: Shows the current status of the time off request. A time off request can have any of the following statuses:
- requested: Initial state of a request that's waiting for employer approval.
- approved: The time off request has been approved by the employer.
  
  ℹ️ Public holidays are always created with an approved status.
- taken: The approved request has been used by the employee. An approved request is automatically marked as taken when the time off date has passed.
- declined: The request was declined by the employer.
- cancel_requested: The employee has requested cancellation of a previously approved request.
- canceled: The request has been canceled.
approved_at: Timestamp at which the request was accepted.
approver_id: Unique ID of the user who accepts the request. This ID matches the ID of a user on Remote platform that has the required permissions to approve/decline the time off requests. You can use the List Company Managers to fetch a list of these users.
notes: Additional notes can be added to the request using this field.

Attaching Reference Document

The Remote API allows attaching reference documents while creating a time off request as well. The document field of this endpoint requires two fields:

content: contains the file's binary encoded using the Base64 algorithm.
name: represents the filename of the binary file, not the full file path.

This feature is useful if you want to attach useful documents that solidify your time off request. For example, attaching a doctor's prescription advising complete rest or a death certificate in case of a bereavement leave.

timeoff.requested webhook

Every time an employee creates a new time off request and submits it for review, the timeoff.requested webhook is triggered notifying the employer that employment_id has submitted a timeoff_id request for approval.

Show Time Off Request

Now that there's a new time off request, the company manager needs to review the request and decide whether to accept or decline. To get complete details of the incoming request, you can use the Show Time Off endpoint by passing the employment_id received in response to the above registered webhook.

Approve Time Off Request

To approve a time off request, you can call the Approve Time Off endpoint, which takes the timeoff_id and an approver_id. On successful execution, you will notice in the response body that the status is changed from requested to approved.

timeoff.approved webhook

This event is triggered when a timeoff is approved by the company manager and the status of the request is set to approved.

Automatically approved time off

Remote automatically creates and approves public holidays for employees based on their location. For all public holidays, the timeoff.approved webhook is triggered. However, regional holidays need to be requested by the employer and approved by the employee like any other time off request. In that case, the timeoff.requested webhook is triggered.

ℹ️ In case 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 changes when creating time off records. This is called an Observed holiday.

Decline Time Off Request

To decline a submitted time off request, call the Decline Time Off endpoint. Any request that has requested status can be declined using this endpoint. To make a call, you need to provide the timeoff_id endpoint, and optionally, you can also give a reason for declining the request. The status of a time off request is set to declined.

timeoff.declined webhook

This event is triggered whenever a time off request is declined by the company manager.

Update Time Off Request

ℹ️ Updating the status of a time off request through this endpoint is deprecated and will be removed on January 13, 2025.

If an accepted request needs an update, it can be changed using the Update Time Off endpoint. The employee needs to add a reason for the change in the edit_reason field.

--data '{
  "timeoff_type": "paid_time_off",
  "edit_reason": "Selecting the correct time off type."
}'

ℹ️ If the start_date or end_date field is changed, it is crucial to reflect these changes in the timeoff_days field as well.

timeoff.updated webhook

This event is triggered whenever a change is made to an approved request using the update time off endpoint. This webhook is sensitive to every change made to a request at any stage.

timeoff.date_changed webhook

This event is triggered whenever an employee changes the requested dates of the time off request.

Cancel Time Off Request

ℹ️ Currently, it is not possible to cancel a time off request through the Remote API if its status is taken. However, the employee can cancel it using the Remote Platform.

If an already approved time off request needs to be canceled, the Cancel Time Off endpoint is used. Simply update the status to canceled and provide a cancel_reason.

--data '{
  "status": "cancelled",
  "cancel_reason": "Not taking this leave anymore."
}'

timeoff.canceled webhook

This event is triggered when an employee changes the status of a time off request from approved to canceled.

timeoff.taken Webhook

When the requested time off date has passed, the status of the request is changed from approved to taken. When this happens, this event is triggered notifying the employer that employment_id has used the requested time off.

List All Time Off Requests

To list all time off requests of all statuses, you can use the List Time Off endpoint. This returns a detailed list of all requests added by the employees of a company. You can filter the results by employment_id or specific status of a request, etc. For example, if you want to view all pending requests, you can make the following call and review the requests.

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