GET

List time off requests for an employee (absences / holidays)

Scope: team:time-off.read https://api.alladdin.com/api/v2/employees/{employeeId}/time-offs

Returns time off requests (absences, holidays, vacations, sick leave, etc.) for the specified employee, ordered by start date descending. The start_date_from / start_date_to range is required.

Parameters

Path parameters

employeeId string required

Employee ID (24-character hexadecimal ObjectId)

Query parameters

cursor string optional limit integer optional = 50 start_date_from string<date> required

Start date lower bound (YYYY-MM-DD)

start_date_to string<date> required

Start date upper bound (YYYY-MM-DD)

status string optional

Filter by status

"pending" "accepted" "rejected" "cancelled" time_off_type_id string optional

Filter by absence / time off type (e.g. holiday, sick leave, vacation)

Request

python

import requests

url = "https://api.alladdin.com/api/v2/employees/507f1f77bcf86cd799439012/time-offs?cursor=value&limit=50&start_date_from=2026-01-01"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

response = requests.get(url, headers=headers)
print(response.json())

Responses

Response

json

{
  "items": [
    {
      "id": "507f1f77bcf86cd799439011",
      "employee_id": "507f1f77bcf86cd799439012",
      "time_off_type_id": "507f1f77bcf86cd799439013",
      "time_off_type_name": "Vacation",
      "start_date": "2026-06-01",
      "end_date": "2026-06-05",
      "status": "pending",
      "days": "5"
    }
  ],
  "cursor": "string",
  "has_more": true
}

Success responses

200 List of time off requests application/json object items[] object[] id string

Unique identifier of the time off request

employee_id string | null

Identifier of the employee. Null when assigned to a workplace.

time_off_type_id string | null

Identifier of the time off type

time_off_type_name string | null

Name of the time off type

start_date string<date>

Start date of the absence (YYYY-MM-DD, Europe/Madrid)

end_date string<date> | null

End date of the absence (YYYY-MM-DD, Europe/Madrid). Null for single-day requests.

status string | null

Current approval status

Enum: pending accepted rejected cancelled `` days string

Number of days consumed (as a decimal string)

cursor string | null

Opaque cursor pointing to the next page. Pass as cursor in the next request. Null when there is no next page.

has_more boolean

Whether more pages are available after this one

Error responses

400 Bad request application/json 401 Invalid or missing API key application/json 403 Insufficient permissions application/json 404 Employee not found application/json 429 Rate limit exceeded application/json

← PreviousUpdate time off end date (absence / holiday) →

Next →Get a time off request (absence / holiday) →

Alladdin