Vacation Tracker Docs
REST API v2API referenceLocations

Get a location's leave policy for a leave type

This API method returns the active leave policy of a leave type in a location. Requires `leave-policies:read`. Errors: `404 RESOURCE_NOT_FOUND` (the location does not exist or is outside the key's data reach, or the leave type has no active policy in it; `details.resource` is `location` or `leavePolicy`).

GET
/v2/locations/{id}/leave-policies/{leaveTypeId}

Authorization

bearerAuth leave-policies: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: leave-policies:read

Path Parameters

id*string

resource ID.

leaveTypeId*string

leave type ID.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/locations/string/leave-policies/string"
{
  "data": {
    "locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
    "leaveTypeId": "leaveType-fcc1e5c5-ba93-479d-bd58-8f860ba10615",
    "isActive": true,
    "quotaUnit": "days",
    "daysPerYear": 20,
    "hoursPerYear": 160,
    "maxRolloverDays": 5,
    "maxRolloverHours": 40,
    "hasUnlimitedDays": false,
    "isApprovalRequired": true,
    "isReasonRequired": false,
    "hideLeaveType": false,
    "allowLeaveInPast": false,
    "negativeBalanceAllowed": false,
    "shortestLeaveInterval": "HALF-DAY",
    "negativeBroughtForwardAllowed": false,
    "accrual": {
      "type": "MONTHLY",
      "capRate": 2,
      "firstEarningDate": "2026-01-01",
      "periodStart": "2026-01-01",
      "allowAdvanceUsage": false,
      "pauseWhenUserDeactivated": true
    },
    "broughtForwardExpiration": {
      "enabled": true,
      "month": 3,
      "day": 31
    },
    "toil": {
      "enabled": false
    }
  }
}
{
  "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

List a location's leave policies

This API method returns the active leave policies of a location, one per enabled leave type, in one response without pagination. Requires `leave-policies:read`. Disabled policies are left out. Errors: `404 RESOURCE_NOT_FOUND` (the location does not exist or is outside the key's data reach).

Change a location's leave policy for a leave type

This API method changes the active leave policy of a leave type in a location. Requires `leave-policies:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the change and returns the policy with `200`, or `202 Accepted` with an operation to poll. - Send only the fields you want to change. They are merged with the active policy, and `accrual`, `broughtForwardExpiration` and `toil` are merged field by field. - The merged policy must pass the same validation as `PUT`: for example, switching `accrual.type` from `NONE` to an accruing type also needs its dates. Switching to `NONE` drops the stored `accrual.periodStart`. - Some older accruing policies have no `accrual.periodStart`. When you don't send one, a `MONTHLY` or `SEMI-MONTHLY` policy gets the current accrual period (from the location's time zone and year start day) and its `firstEarningDate` moves into that period, as saving the policy in Vacation Tracker does. A `WEEKLY` or `BI-WEEKLY` policy fails with `400 VALIDATION_ERROR` on `accrual.periodStart`: send the date with the update. - `resetUserOverrides` and `broughtForwardExpiration.applyToPastYear` apply only when you send them in this request. - A leave type without an active policy in this location returns `404`; enable it with `PUT` first. Errors: `400 VALIDATION_ERROR` (`details.fields`), `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `403 FEATURE_NOT_IN_PLAN` (an accruing `accrual.type`, `toil.enabled: true`, or a `ONE-HOUR`, `HALF-HOUR` or `FIFTEEN-MINUTES` `shortestLeaveInterval` when the plan does not include it; `details.settings` lists them. Settings the policy already has are accepted), `404 RESOURCE_NOT_FOUND` (the location does not exist or is outside the key's data reach, the leave type does not exist or was deleted, or it has no active policy here; `details.resource` is `location`, `leaveType` or `leavePolicy`), and the `Idempotency-Key` codes.