POST

Create a time off request (absence / holiday)

Scope:team:time-off.write

https://api.holded.com/api/v2/employees/{employeeId}/time-offs

Creates a new time off request (absence, holiday, vacation, sick leave, etc.) for the specified employee.

Parameters

Path parameters

employeeIdstringrequired

Employee ID (24-character hexadecimal ObjectId)

Request body

object

time_off_type_idstringrequired

Time off type identifier (e.g. holiday, sick leave, vacation, parental leave)

start_datestring<date>required

Start date (YYYY-MM-DD)

end_datestring<date>required

End date (YYYY-MM-DD). Equal to start_date for single-day requests.

start_periodstring | nulloptional

Half-day granularity: morning, afternoon, full_day

Enum:morningafternoonfull_dayhourly

reasonstring | nulloptional

Optional note or reason

start_hourstring | nulloptional

Start time for HOURS-granularity types (HH:MM)

num_hoursnumber | nulloptional

Duration in hours. Multiple of 0.5.

Request

python

import requests

url = "https://api.holded.com/api/v2/employees/507f1f77bcf86cd799439012/time-offs"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

payload = {
    "time_off_type_id": "507f1f77bcf86cd799439013",
    "start_date": "2026-06-01",
    "end_date": "2026-06-05",
    "start_period": "morning",
    "reason": "string",
    "start_hour": "09:00",
    "num_hours": 4
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

Responses

Response

json

{
  "id": "507f1f77bcf86cd799439011"
}

Success responses

201Absence / time off request createdapplication/json

object

idstring

Error responses

400Bad requestapplication/json

401Invalid or missing API keyapplication/json

403Insufficient permissionsapplication/json

404Employee not foundapplication/json

422Invalid time off dataapplication/json

429Rate limit exceededapplication/json