Vacation Tracker Docs
REST API v2API referenceToil

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.

POST
/v2/toil

Authorization

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

Header Parameters

Idempotency-Key?string

optional key (1 to 255 printable ASCII characters) that makes a write request safe to retry. Keys are retained for 24 hours per API key. Retrying with the same key and the same request within those 24 hours replays the original response (with the Idempotent-Replayed header). Reusing the key with a different request returns 422 IDEMPOTENCY_KEY_REUSED; retrying while the first request is still running returns 409 IDEMPOTENCY_REQUEST_IN_PROGRESS; an invalid key returns 400 INVALID_IDEMPOTENCY_KEY.

Length1 <= length <= 255
X-On-Behalf-Of?string

ID of the user the write is performed for. Requires the users:act-on-behalf scope, and the key owner must manage the target user; otherwise the request fails with 403 ON_BEHALF_OF_NOT_ALLOWED. Ignored on GET requests.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v2/toil" \  -H "Content-Type: application/json" \  -d '{    "leaveTypeId": "leaveType-fcc1e5c5-ba93-479d-bd58-8f860ba10615",    "startDate": "2026-11-07",    "endDate": "2026-11-07",    "reason": "Worked on the weekend release"  }'
{
  "data": {
    "id": "toilRequest-3b8e6c1a-2d4f-4b7a-9c5e-8f1a2b3c4d5e",
    "userId": "user-63b17e97-d38b-4586-8498-bb4f5d2e2c14",
    "approverId": "user-0f3a9c1e-6c2b-4a5d-9e7f-1b2c3d4e5f60",
    "leaveTypeId": "leaveType-fcc1e5c5-ba93-479d-bd58-8f860ba10615",
    "startDate": "2026-11-07",
    "endDate": "2026-11-07",
    "isFullDayLeave": true,
    "durationWorkingDays": 1,
    "locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
    "departmentId": "team-0a21c25e-6925-4a5b-90ee-ecf82096c4f6",
    "status": "APPROVED",
    "reason": "Worked on the weekend release",
    "statusReason": null,
    "approvalDate": "2026-11-09T08:30:00.000Z",
    "createdAt": "2026-11-08T17:45:12.000Z"
  }
}
{
  "operation": {
    "id": "pa_3f1c2b9e-8a47-4d5e-9c61-2b7f0e4a1d93",
    "status": "PENDING",
    "url": "/v2/operations/pa_3f1c2b9e-8a47-4d5e-9c61-2b7f0e4a1d93"
  }
}
{
  "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": "RESOURCE_NOT_FOUND",
    "name": "ResourceNotFound",
    "description": "The requested resource does not exist or is outside the data this key can access.",
    "resolution": "Check the ID of the resource named in details.resource and that the key owner can see it.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "name": "Conflict",
    "description": "The request conflicts with the current state of the resource.",
    "resolution": "Read the resource again and retry with up-to-date values.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

{
  "error": {
    "code": "LEAVE_NEGATIVE_BALANCE",
    "name": "LeaveNegativeBalance",
    "description": "The user does not have enough balance for this leave.",
    "resolution": "Shorten the leave, use a different leave type, or ask an admin to adjust the quota.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

{
  "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

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 a TOIL request

This API method returns a single TOIL request. Requires `toil:read`. Errors: `404 RESOURCE_NOT_FOUND` (the TOIL request does not exist, or belongs to a user outside the key's data reach).