Vacation TrackerDeveloper Docs
REST API v2API referenceLeaves

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.
  • reason and statusReason are the reason the user gave and the one the approver gave, so they need leaves:read-reason on top of leaves:read. Without it both come back as null and every other field is unchanged, which is enough to tell who is away, when, and whether it was approved.
  • Each expand value needs the read scope of the resource it embeds: user and approver need users:read, leaveType needs leave-types:read. Without it the request fails with 403 INSUFFICIENT_SCOPE, and details.expand names the values that asked for it. Drop them, or add the scopes to the key. userId, approverId and leaveTypeId are always returned, so a key with only leaves:read can still match leaves to users and leave types by ID.
  • An embedded user or approver carries location and department, which the request never named. A key without locations:read or departments:read keeps the request and loses the nested object; locationId and departmentId stay.
  • 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), 400 INVALID_PAGINATION_TOKEN and 403 INSUFFICIENT_SCOPE (an expand value whose read scope the key does not have).

GET
/v2/leaves

Authorization

bearerAuth leaves:read
AuthorizationBearer <token>

API 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

startDate*string

date in YYYY-MM-DD format.

Formatdate
endDate*string

date in YYYY-MM-DD format, can't be before the startDate.

Formatdate
status?string

leave request status, by default 'APPROVED'.

Default"APPROVED"
Value in"APPROVED" | "OPEN" | "DENIED" | "CANCELLED" | "EXPIRED" | "DELETED"
limit?integer

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.

Default200
Range1 <= value <= 1000
nextToken?string

The 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.

expand?array<>

a comma-separated list of related resources to include in each leave. Options: user (the person on leave, requires users:read), approver (who approved or denied it, requires users:read) and leaveType (the leave type, requires leave-types:read). Each value needs the read scope of the resource it embeds.

Value in"user" | "approver" | "leaveType"

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.io

Delete 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.

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.