Vacation TrackerDeveloper Docs
REST API v2API referenceToil

Get a TOIL request

This API method returns a single TOIL request. Requires toil:read. reason and statusReason need leaves:read-reason on top of it, the same scope that unmasks them on leaves; without it both come back as null and every other field is unchanged.

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.

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.