Vacation TrackerDeveloper Docs
REST API v2API referenceUsers

Get a user's leave quotas

This API method returns the quota (the base entitlement before rollover, seniority, TOIL and usage) of each leave type in the user's location, for one leave period. Use GET /v2/users/{id}/balances for remaining balances.

Requires users:read. Each quota's amount is in that quota's unit (days or hours), as set on the leave policy or on the user's custom quota. isCustom is true when the quota was set for this user instead of coming from the location's leave policy. Only active leave types are included. A key without leave-types:read-hidden gets Hidden Leave Type as leaveTypeName for leave types hidden by the policy of the user's location; leaveTypeId and amount are unchanged. period is the only query parameter accepted; any other one fails validation.

Errors: 400 VALIDATION_ERROR (an invalid period or an unknown query parameter), 400 QUOTA_PERIOD_NOT_AVAILABLE (the user has no leave period that contains today, or no next period), and 404 RESOURCE_NOT_FOUND (the user does not exist or is outside the key's data reach).

GET
/v2/users/{id}/quotas

Authorization

bearerAuth users: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: users:read

Path Parameters

id*string

resource ID.

Query Parameters

period?string

current returns the leave period that contains today, next returns the leave period after it. Default is current.

Default"current"
Value in"current" | "next"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/users/string/quotas"
{
  "data": {
    "userId": "user-cfe5d39b-f1f0-45aa-85cd-ce93e637a262",
    "period": {
      "start": "2026-01-01",
      "end": "2026-12-31"
    },
    "quotas": [
      {
        "leaveTypeId": "leaveType-fcc1e5c5-ba93-479d-bd58-8f860ba10615",
        "leaveTypeName": "Vacation",
        "unlimited": false,
        "amount": 25,
        "unit": "days",
        "isCustom": true,
        "prorate": false,
        "ignoreRolloverFromPreviousYear": false
      },
      {
        "leaveTypeId": "leaveType-88681ca1-4a47-4e4d-bc35-ffff86c0f54e",
        "leaveTypeName": "Sick leave",
        "unlimited": true,
        "amount": 0,
        "unit": "days",
        "isCustom": false,
        "prorate": false,
        "ignoreRolloverFromPreviousYear": false
      }
    ]
  }
}
{
  "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": "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

Set a user's custom work week

This API method gives a user their own work week, overriding their location's work week. Requires users:write. This is a full replacement, not a merge. Send exactly one of:

Set a user's quota for a leave type

This API method sets a user's quota for one leave type, the same way as editing it on the user's page in the Vacation Tracker dashboard. Requires users:write. This is a full replacement of the quota settings for the chosen period: fields you omit take their defaults.