Returns a collection of time off requests. Required scope: r_timeoff.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
This endpoint uses ther_timeoffscope, which can be enabled through the Integrations section found within the Settings menu.
Token behaviour
This endpoint supports both user tokens and account tokens.
Account token — when employee_id and employee_ids are omitted, the response contains every time off request in the account. Either parameter can be used to scope the result to specific employees.
User token — when employee_id and employee_ids are omitted, the response contains the authenticated user's own requests plus those of all direct and indirect descendants in the org chart. Users with the time off requests view permission receive every request in the account regardless of the org chart.
When either filter is provided, the user token is authorized per employee: if any supplied id cannot be viewed, the request fails with 403.
When both employee_id and employee_ids are provided, the values are merged and deduplicated.
Results
Calling the /timeoff/requests endpoint will return a paginated collection of time off requests between the time frame of from_date and to_date. An example of the response follows:
{
"total_count": 2,
"requests": [
{
"id": "135b",
"employee_id": "4d3",
"from_date": "2024-04-04T00:00:00.000",
"to_date": "2024-04-12T00:00:00.000",
"formatted_period": "04 April 2024 - 12 April 2024",
"state": "approved",
"requesting_total": 7,
"timeoff_tracking_unit": "half_days",
"half_days": [],
"updated_by": "Dan Snow",
"updated_at": "2024-04-04T09:58:08.724Z",
"category_name": "Paid time off ",
"pending_approvals": []
},
{
"id": "135c",
"employee_id": "4d4",
"from_date": "2024-05-02T00:00:00.000",
"to_date": "2024-05-09T00:00:00.000",
"formatted_period": "02 May 2024 - 09 May 2024",
"state": "pending",
"requesting_total": 4,
"timeoff_tracking_unit": "full_days",
"half_days": [],
"updated_by": "Dan Snow",
"updated_at": "2024-04-04T09:58:40.252Z",
"category_name": "Sick leave",
"pending_approvals": []
}
]
}The response object has the following top-level keys:
| key | type | description |
|---|---|---|
| total_count | integer | Total number of requests matching the query, ignoring limit/offset |
| requests | array | Page of time off requests |
Each timeoff request has the following keys:
| key | type | description |
|---|---|---|
| id | string | Unique identifier for the time off request |
| employee_id | string | SPI key of the employee the request belongs to |
| from_date | string | Iso date without timezone string |
| to_date | string | Iso date without timezone string |
| formatted_period | string | More convenient way to display the period of the time off request |
| state | string | Available states are: pending, approved, rejected and canceled |
| requesting_total | integer | Total days that will be deducted from the relevant time off category pool |
| timeoff_tracking_unit | string | full_days, half_days, or hours |
| half_days | string | The days that were counted as half day requests |
| updated_by | string | The full name of the time off requester |
| updated_at | string | Iso date without timezone string |
| pending_approvals | array | List of approvals still awaiting action. Empty array when no approvals are pending |
half_days
| key | type | description |
|---|---|---|
| date | string | Iso date without timezone string |
| half | string | valid options are first and second half of the day |
pending_approvals
| key | type | description |
|---|---|---|
| id | string | SPI key of the approval — used with PATCH /timeoff/approvals/:key |
| approver_id | string | Identifier of the member whose approval action is required |
Query parameters
| parameter | type | description |
|---|---|---|
| from_date | string | Iso date without timezone string. Required. |
| to_date | string | Iso date without timezone string |
| category_ids | string[] | Filter by category ids (see GET /timeoff/categories) |
| states | string[] | Filter by request state: pending, approved, rejected, canceled |
| employee_id | string | Filter by a single employee SPI key. Optional. Merged with employee_ids when both are provided. |
| employee_ids | string[] | Filter by one or more employee SPI keys. Optional. Merged with employee_id when both are provided. |
| limit | integer | Number of results per page. Allowed values: 10, 20, 50, 100. Default 10. |
| offset | integer | Number of requests to skip (for pagination). Default 0. |
Error responses
| Status | Condition |
|---|---|
| 400 | Invalid query parameters (e.g. limit not in the allowed enum, offset negative, malformed from_date) |
| 403 | Missing required scope r_timeoff, or a user token supplied an employee_id/employee_ids value it cannot view |
| 404 | Account token supplied an employee_id that does not belong to the account |