List leaves between two dates
This API method returns a paginated list of leaves that overlap the period between `startDate` and `endDate`, for users within the key's data reach. Requires `leaves:read`. Each leave has the same shape as in API v1. - `status` is matched case-insensitively and defaults to `APPROVED`; one status per request. - The key's data reach is applied after each page is read, so a page can hold fewer than `limit` leaves (even none) while `nextToken` is still returned. Keep paginating until `nextToken` is absent. - A key whose owner sees only their own data gets all of their own leaves in one page, without `nextToken`. - With `expand=leaveType`, a key without `leave-types:read-hidden` gets `Hidden Leave Type` as `leaveType.name` for leaves whose leave policy hides the leave type. `leaveTypeId` is always returned. Errors: `400 VALIDATION_ERROR` (a missing or invalid `startDate`, `endDate`, `status`, `limit` or `expand`, or `endDate` before `startDate`; `details.fields` lists them) and `400 INVALID_PAGINATION_TOKEN`.
Authorization
bearerAuth leaves:readAPI key sent as Authorization: Bearer vt_live_<secret>. See the Authentication and Scopes sections at the top of this document for how keys are created, which scopes exist and how the key owner's role limits them.
In: header
Scope: leaves:read
Query Parameters
date in YYYY-MM-DD format.
datedate in YYYY-MM-DD format, can't be before the startDate.
dateleave request status, by default 'APPROVED'.
"APPROVED""APPROVED" | "OPEN" | "DENIED" | "CANCELLED" | "EXPIRED" | "DELETED"a number of items to return per page, between 1 and 1000, default is 200. The number of returned items might be less than the provided limit even when more pages exist; rely on nextToken. Same semantics as the v1 limit parameter.
2001 <= value <= 1000The nextToken returned by the previous API call. Send the same filters as in the previous call. Same semantics as the v1 nextToken parameter; a token that was not issued by this API fails with 400 INVALID_PAGINATION_TOKEN.
a comma-separated list of related resources to include in each leave.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v2/leaves?startDate=2023-02-03&endDate=2023-03-03&expand=user%2CleaveType"{
"data": [
{
"id": "leaveRequest-cfe5d39b-f1f0-45aa-85cd-ce93e637a262",
"userId": "user-63b17e97-d38b-4586-8498-bb4f5d2e2c14",
"approverId": "user-0f3a9c1e-6c2b-4a5d-9e7f-1b2c3d4e5f60",
"autoApproved": false,
"durationCalendarDays": 5,
"durationWorkingDays": 5,
"startDate": "2026-11-09",
"endDate": "2026-11-13",
"isFullDayLeave": true,
"leaveTypeId": "leaveType-fcc1e5c5-ba93-479d-bd58-8f860ba10615",
"locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
"departmentId": "team-0a21c25e-6925-4a5b-90ee-ecf82096c4f6",
"status": "APPROVED",
"reason": "Family trip",
"statusReason": null,
"approvedLevel": null,
"createdAt": "2026-10-01T09:12:40.062Z"
},
{
"id": "leaveRequest-7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"userId": "user-cfe5d39b-f1f0-45aa-85cd-ce93e637a262",
"autoApproved": true,
"durationCalendarDays": 1,
"durationWorkingDays": 0.5,
"startDate": "2026-11-12",
"endDate": "2026-11-12",
"isFullDayLeave": false,
"startHour": 9,
"endHour": 13,
"startMinute": 0,
"endMinute": 0,
"leaveTypeId": "leaveType-88681ca1-4a47-4e4d-bc35-ffff86c0f54e",
"locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
"departmentId": "team-0a21c25e-6925-4a5b-90ee-ecf82096c4f6",
"status": "APPROVED",
"reason": "",
"statusReason": null,
"approvedLevel": null,
"createdAt": "2026-10-02T14:03:11.410Z"
}
],
"nextToken": "eyJjb21wYW55SWQiOiJjNmFmOWFjNiJ9"
}{
"error": {
"code": "VALIDATION_ERROR",
"name": "ValidationError",
"description": "A query parameter, body field or header failed validation.",
"resolution": "Fix the fields listed in details.fields and send the request again.",
"requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
"details": {
"fields": [
{
"path": "startDate",
"message": "\"startDate\" is required"
}
]
}
}
}{
"error": {
"code": "UNAUTHORIZED",
"name": "Unauthorized",
"description": "The API key is missing, malformed or not recognized.",
"resolution": "Send a valid API key in the Authorization header as Bearer followed by the full vt_live_ key.",
"requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
}
}{
"error": {
"code": "INSUFFICIENT_SCOPE",
"name": "InsufficientScope",
"description": "The API key does not have the scopes this request needs.",
"resolution": "Add the scopes listed in details.requiredScopes to the key in the Vacation Tracker dashboard.",
"requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
"details": {
"requiredScopes": [
"leaves:write"
]
}
}
}{
"error": {
"code": "RATE_LIMITED",
"name": "RateLimited",
"description": "Too many requests were sent in a short time.",
"resolution": "Wait a few seconds and retry, using the same Idempotency-Key for writes.",
"requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
}
}{
"error": {
"code": "INTERNAL_ERROR",
"name": "InternalError",
"description": "Something went wrong on our side.",
"resolution": "Retry later, and if it keeps happening, contact Vacation Tracker support and quote the requestId.",
"requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
}
}Need help?
developers@vacationtracker.ioDelete a leave type
This API method deletes a leave type. Requires `leave-types:write`. No request body. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the deletion and returns `204`, or `202 Accepted` with an operation to poll. **Warning:** deleting a leave type cancels every `OPEN` and `APPROVED` leave of that type, from yesterday through five years in the future. This cannot be undone. To stop new requests but keep existing leaves, set `isActive` to `false` with `PATCH /v2/leave-types/{id}` instead. Errors: `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the leave type does not exist or was already deleted), and the `Idempotency-Key` codes.
Create a leave
This API method creates a leave. Requires `leaves:write`. It waits for the leave to be created and returns it with `201`; if that takes longer than the wait window it returns `202 Accepted` with an operation to poll. - Omit `userId` (or set it to the acting user's ID) to request a leave for the acting user. The leave is pending approval (`OPEN`) unless the leave policy needs no approval, in which case it is returned `APPROVED`. Every rule of the user's leave policy applies, as in the Vacation Tracker dashboard. - Set `userId` to another user's ID to add an already approved leave for a user the acting user manages. This also requires the `leaves:approve` scope, and the user must be within the key's data reach. Only overlapping leaves, dates without working days and part-day leaves longer than a working day block the leave; the other policy rules are not applied. - The acting user is the key owner, or the user in the `X-On-Behalf-Of` header, for example to request a pending leave in an employee's name. **Automations.** If the leave breaks an automation (a blackout period, maximum users away, a probation period, a leave duration limit or a notice period), the request fails with `409 AUTOMATION_OVERRIDE_REQUIRED` and `details.warnings` lists each violation. When adding a leave for another user, repeat the request with every listed `code` in `overrideAutomations` to add the leave anyway. Overrides are not applied to the acting user's own leave requests, so such a leave is rejected with the matching `422` code (`LEAVE_BLACKOUT_PERIOD`, `LEAVE_MAXIMUM_USERS_AWAY`, `LEAVE_PROBATION_PERIOD`, `LEAVE_DURATION_LIMIT` or `LEAVE_NOTICE_PERIOD`). Errors: `400 VALIDATION_ERROR` (`details.fields`), `403 INSUFFICIENT_SCOPE` (`leaves:approve` missing when adding for another user), `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the user is outside the key's data reach or does not exist), `409 AUTOMATION_OVERRIDE_REQUIRED`, `422 LEAVE_OVERLAP`, `422 LEAVE_NO_WORKING_DAYS`, `422 LEAVE_INVALID_DATE_RANGE`, `422 LEAVE_INVALID_DURATION`, `422 LEAVE_INVALID_HALF_DAY_DURATION`, `422 LEAVE_START_DATE_IN_PAST`, `422 LEAVE_NEGATIVE_BALANCE`, `422 LEAVE_REASON_REQUIRED`, `422 LEAVE_TYPE_INACTIVE`, `422 LEAVE_POLICY_MISSING`, `422 USER_NOT_EMPLOYED_ON_DATES`, the automation codes above, and the `Idempotency-Key` codes.