Vacation Tracker Docs
REST API v2API referenceToil

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

GET
/v2/toil/{id}

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

Path Parameters

id*string

resource ID.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/toil/string"
{
  "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"
  }
}
{
  "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": "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

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.

Update a TOIL request

This API method changes a TOIL request. Requires `toil:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the change and returns the TOIL request with `200`, or `202 Accepted` with an operation to poll. Send only the fields you want to change; at least one field is required. The change is merged with the request's current state: fields you omit keep their current value. - The time fields are accepted only together with `isFullDayLeave: false`, and then all four are required. Without `isFullDayLeave`, the stored full-day or part-day times are kept. - `isFullDayLeave: true` turns the request into full days. Errors: `400 VALIDATION_ERROR` (`details.fields`), `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the TOIL request does not exist or is outside the key's data reach), `409 CONFLICT`, `422 TOIL_NOT_ALLOWED`, `422 TOIL_OVERLAP`, `422 TOIL_INVALID_REQUEST`, `422 TOIL_REASON_REQUIRED`, `422 TOIL_REQUEST_NOT_OPEN`, `422 REQUEST_REJECTED`, and the `Idempotency-Key` codes.