Time Off API Endpoints

This guide provides details on how to interact with the Time Off API through its various endpoints.

Scenario: An employee submits a time off request. This request needs to be reviewed, approved, updated, or canceled.

Check Time Off Request Type

Before creating a time off request, you need to retrieve the available time off types.

The List Time Off Types endpoint returns a list of available types of time off requests.

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

The response of this call will be the following.

Click to view the response.

{
  "data": {
    "timeoff_types": [
      {
        "name": "paid_time_off",
        "description": "Yearly paid vacation days granted to employees."
      },
      {
        "name": "sick_leave",
        "description": "Leave granted when an employee is too sick to work. Sick leave can be paid or unpaid."
      },
      {
        "name": "public_holiday",
        "description": "A nationally or regionally recognized day when most businesses and other institutions are closed."
      },
      {
        "name": "unpaid_leave",
        "description": "Leave granted to an employee during which they are not compensated."
      },
      {
        "name": "extended_leave",
        "description": "Leave taken over a longer period of time."
      },
      {
        "name": "in_lieu_time",
        "description": "Leave granted to an employee instead of pay for work performed outside of their contracted days/hours."
      },
      {
        "name": "maternity_leave",
        "description": "Leave granted to a mother for the birth of her child."
      },
      {
        "name": "paternity_leave",
        "description": "Leave granted to a father for the birth of their child."
      },
      {
        "name": "parental_leave",
        "description": "Leave granted to parents to care for their children."
      },
      {
        "name": "bereavement",
        "description": "Leave granted following the death of a close relative. Bereavement leave can be paid or unpaid."
      },
      {
        "name": "military_leave",
        "description": "Leave granted to an employee to perform military duty."
      },
      {
        "name": "other",
        "description": "Leave types that are not covered by the categories above."
      }
    ]
  }
}

Create New Time Off Request

Once you have the list, you can call the Create Time Off endpoint that creates a new time off request. The API currently supports only approved requests at creation time.

curl --location --request POST \
  --header "Authorization: Bearer <your token>" \
  --header "Content-Type: application/json" \
  https://gateway.remote-sandbox.com/v1/timeoff \
  --data '{
	"start_date": "2024-10-31",
  "end_date": "2024-11-02",
  "employment_id": "5509b6b0-5a0a-11ed-a6f6-c38dbde70e6f",
  "timeoff_days": [
    {day: "2024-10-31", hours: 8},
    {day: "2024-11-01", hours: 8},
    {day: "2024-11-02", hours: 8}
  ],
  "timeoff_type": "paid_time_off",
  "timezone": "Etc/UTC",
  "status": "approved",
  "approver_id": "e55eedbe-7c17-46e4-bdd2-2b63d56eb2fc",
  "approved_at": "2024-10-27T15:03:23Z"
}'

The important fields in this response are:

start_date: the first day of leave.
end_date: the last day of leave.
employment_id: ID of the employee that's requesting time off.
timeoff_days: defines the exact days and hours for the time off request.
timeoff-type: defines the type of leave (refer to the section above for details).
timezone: defines the timezone of the dates mentioned in the request.
status: the current status of this time off request.
approver_id: ID of the employer who accepts the request.
approved_at: timestamp at which the request was accepted.

Attaching Reference Document

The Remote API allows attaching reference document with the create time off request. The document field requires two nested fields:

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

This is useful if you want to attach, let's say, a doctor's prescription telling you to take a rest along with your sick leave request. In this case, attaching additional documents will help get your request accepted easily.

--data '{
	"start_date": "2024-10-31",
  "end_date": "2024-11-02",
  "employment_id": "5509b6b0-5a0a-11ed-a6f6-c38dbde70e6f",
  "timeoff_days": [
    ...
  ],
  "timeoff_type": "sick_leave",
  "timezone": "Etc/UTC",
  "status": "approved",
  "approver_id": "e55eedbe-7c17-46e4-bdd2-2b63d56eb2fc",
  "approved_at": "2024-10-27T15:03:23Z",
  "document": {
    "content": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjMgMCBvYmoKPDwgL0Zpb...",
    "name": "doctor-prescription.pdf"
  }
}'

Review Time Off Requests

Now that there's a new time off request, the employer needs to review the request and decide whether to approve or cancel the request. You can use the List Time Off endpoint to review time off requests.

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

These requests can be filtered by employment_id.

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

Or by status. For instance, the following request will return time off requests that have been approved.

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

Approve Time Off Request

Once the request has been reviewed, it can be approved using the Approve Time Off endpoint.

curl --request POST \
     --url https://gateway.remote-sandbox.com/v1/timeoff/<timeoff-id>/approve \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_token>' \
     --header 'content-type: application/json' \
     --data '
{
  "approver_id": "<employer_id>"
}
'

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 to be changed, it can be updated through Update Time Off. You will need 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's crucial to reflect these changes in the timeoff_days field as well, as described in the timeoff_days field section.

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.

In cases where a time off request needs to be canceled, you can use the Cancel Time Off endpoint. You are required to update the status to canceled and provide a cancel_reason as follows:

curl --location --request PATCH \
  --header "Authorization: Bearer <your token>" \
  --header "Content-Type: application/json" \
  https://gateway.remote-sandbox.com/v1/timeoff/daba19dc-61e7-11ed-97bb-5bf1862b6b44 \
  --data '{
  "status": "cancelled",
  "cancel_reason": "Not taking this leave anymore."
}'

View Specific Time Off Request

To view the status and details of a particular time off request, you can use the Show Time Off endpoint by providing a time off ID.

curl --request GET \
     --url https://gateway.remote-sandbox.com/v1/timeoff/<timeoff_id> \
     --header 'Authorization: Bearer <your_token>' \
     --header 'accept: application/json'