🚧

This endpoint uses the w_timeoff scope, which can be enabled through the Integrations section found within the Settings menu.

Token behaviour

This endpoint supports both user tokens and account tokens.

User token — employee_id and member_id are optional. When omitted, the employee and member are derived from the authenticated user.

Account token — employee_id and member_id are required. member_id identifies the member context for the request (used to track who created the request).

Example request with account token

{
  "employee_id": "4d3",
  "member_id": "188948e7-28fb-460e-85fe-79de4cd7926f:1839d70f-7caa-4f02-9e3f-c46cced76f5b",
  "category_id": "4d3",
  "from_date": "2024-03-26T12:00:00.000",
  "to_date": "2024-03-28T12:00:00.000",
  "note": "Optional note"
}

Example request with user token

{
  "category_id": "4d3",
  "from_date": "2024-03-26T12:00:00.000",
  "to_date": "2024-03-28T12:00:00.000",
  "note": "Optional note"
}

Validation rules

from_date, to_date and every half_days[].date are ISO 8601 date-times without a timezone, with required milliseconds — format YYYY-MM-DDTHH:mm:ss.SSS.

Additional constraints:

• to_date must be on or after from_date (same day is allowed).
• to_date must be within less than 3 calendar years of from_date. Internally the check is differenceInYears(to_date, from_date) ≤ 2, which floors — so e.g. from_date = 2024-01-01 with to_date = 2026-12-31 is accepted but to_date = 2027-01-01 is rejected.
• from_date must be on or after the employee's start date (truncated to the start of day). Requesting time off before the employee's start_date returns 400 with message fromDate can't be less than {startDate}.

Response

The response includes the created time off request. If the category requires approvals, pending_approvals will list the approvers whose action is still required.

pending_approvals