Vacation TrackerDeveloper 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 1000 and defaults to 200, the same as GET /v2/leaves and GET /v2/users.
  • 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.
  • reason and statusReason are the reason the user gave and the one the approver gave, so they need leaves:read-reason on top of toil:read. That one scope covers leaves and TOIL alike. Without it both come back as null and every other field is unchanged.

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 1000, default is 200. The number of returned items might be less than the provided limit even when more pages exist; rely on nextToken.

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.

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.

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.