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.

Authorization

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

Path Parameters

id*string

resource ID.

leaveTypeId*string

leave type ID.

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.

quotaUnit?string

the unit the quota is set in

Value in"days" | "hours"

daysPerYear?number

the yearly quota in days

Range0 <= value <= 365

hoursPerYear?number

the yearly quota in hours

Range0 <= value <= 2920

maxRolloverDays?number

the maximum number of unused days that roll over into the next leave year

Range0 <= value <= 365

maxRolloverHours?number

the maximum number of unused hours that roll over into the next leave year

Range0 <= value <= 2920

hasUnlimitedDays?boolean

whether the leave type grants unlimited leave in this location

isApprovalRequired?boolean

whether leaves of this type need approval in this location

isReasonRequired?boolean

whether a reason is required

hideLeaveType?boolean

whether the leave type is hidden from users in this location when they request leave

allowLeaveInPast?boolean

whether users can request leave for past dates

negativeBalanceAllowed?boolean

whether a user's balance can go negative

negativeBroughtForwardAllowed?boolean

whether a negative balance is brought forward into the next leave year

shortestLeaveInterval?ShortestLeaveInterval

the smallest unit of leave a user can request

Value in"FULL-DAY" | "HALF-DAY" | "ONE-HOUR" | "HALF-HOUR" | "FIFTEEN-MINUTES"

accrual?

accrual fields to change, merged field by field with the current accrual. The merged accrual must meet the same rules as in PUT; switching to NONE drops the stored periodStart.

broughtForwardExpiration?

toil?

resetUserOverrides?boolean

one-time action, never stored or returned. When true, clears every per-user override of this policy in this location.

Response Body

`application/json`

curl -X PATCH "https://example.com/v2/locations/string/leave-policies/string" \  -H "Content-Type: application/json" \  -d '{    "daysPerYear": 25,    "resetUserOverrides": true  }'

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

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

Change a location's leave policy for a leave type

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

200application/json

202application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

Key lacks a required scope

Key was revoked

Acting user may not perform the action

The request conflicts with the current state

The default location cannot be deleted

The leave needs more balance than the user has

The leave was already approved, denied or cancelled

TOIL is not enabled for the leave type

The Idempotency-Key was used with a different request

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`