Vacation Tracker Docs
REST API v2API referenceToil

List TOIL requests between two dates

This API method returns a paginated list of TOIL requests that overlap the period between `startDate` and `endDate`, for users within the key's data reach. Requires `toil:read`. - `status` is optional; without it, TOIL requests in every status are returned. Unlike `GET /v2/leaves`, the value is case-sensitive. - `limit` is between 1 and 100 and defaults to 50. - The key's data reach is applied after each page is read, so a page can hold fewer than `limit` items (even none) while `nextToken` is still returned. Keep paginating until `nextToken` is absent. Errors: `400 VALIDATION_ERROR` (a missing or invalid `startDate`, `endDate`, `status` or `limit`, or `endDate` before `startDate`; `details.fields` lists them) and `400 INVALID_PAGINATION_TOKEN`.

GET
/v2/toil

Authorization

bearerAuth toil: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: toil: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

TOIL request status. When omitted, TOIL requests in every status are returned.

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

a number of TOIL requests to return per page, between 1 and 100, default is 50. The number of returned items might be less than the provided limit even when more pages exist; rely on nextToken.

Default50
Range1 <= value <= 100
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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/toil?startDate=2023-02-03&endDate=2023-03-03"
{
  "data": [
    {
      "id": "toilRequest-3b8e6c1a-2d4f-4b7a-9c5e-8f1a2b3c4d5e",
      "userId": "user-63b17e97-d38b-4586-8498-bb4f5d2e2c14",
      "approverId": null,
      "leaveTypeId": "leaveType-fcc1e5c5-ba93-479d-bd58-8f860ba10615",
      "startDate": "2026-11-07",
      "endDate": "2026-11-07",
      "isFullDayLeave": false,
      "startHour": 10,
      "endHour": 14,
      "startMinute": 0,
      "endMinute": 0,
      "durationWorkingDays": 0.5,
      "locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
      "departmentId": "team-0a21c25e-6925-4a5b-90ee-ecf82096c4f6",
      "status": "OPEN",
      "reason": "Covered the Saturday on-call shift",
      "statusReason": null,
      "approvalDate": null,
      "createdAt": "2026-11-08T17:45:12.000Z"
    }
  ],
  "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

Cancel a leave

This API method cancels an `OPEN` or `APPROVED` leave. Requires `leaves:write`. The acting user (the key owner, or the `X-On-Behalf-Of` user) can cancel their own leaves, or the leaves of users they manage. The request body is optional; `reason` is stored as the leave's `statusReason`. It waits for the cancellation and returns the leave with `200`, or `202 Accepted` with an operation to poll. Errors: `400 VALIDATION_ERROR` (`details.fields`), `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the leave does not exist or is outside the key's data reach), `422 LEAVE_REQUEST_NOT_EDITABLE` (the leave can no longer be cancelled), and the `Idempotency-Key` codes.

Create a TOIL request

This API method creates a TOIL (time off in lieu) request. Requires `toil:write`. TOIL must be enabled for the leave type in the user's leave policy. It waits for the request to be created and returns it with `201`, or `202 Accepted` with an operation to poll. TOIL writes may return `202 Accepted` more often than leave writes. - Omit `userId` (or set it to the acting user's ID) to request TOIL for the acting user. The request is pending approval (`OPEN`) unless the policy needs no approval. - Set `userId` to another user's ID to add approved TOIL 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. - The acting user is the key owner, or the user in the `X-On-Behalf-Of` header. The same validation as in the Vacation Tracker dashboard runs before anything is created. 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` (the acting user is not an approver of the user), `404 RESOURCE_NOT_FOUND` (the user is outside the key's data reach), `409 CONFLICT` (the same TOIL request already exists), `422 TOIL_NOT_ALLOWED` (TOIL is not enabled for the leave type, user, plan or role), `422 TOIL_OVERLAP`, `422 TOIL_INVALID_REQUEST` (invalid dates, minutes or duration), `422 TOIL_REASON_REQUIRED`, `422 REQUEST_REJECTED`, and the `Idempotency-Key` codes.