Disable a location's leave policy for a leave type
This API method disables the leave policy of a leave type in a location, so users in that location can no longer request that leave type. Requires `leave-policies:write`. No request body. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the change and returns `204`, or `202 Accepted` with an operation to poll. The leave type itself is not deleted; enable the policy again with `PUT`. Errors: `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `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), and the `Idempotency-Key` codes.
Authorization
bearerAuth leave-policies:writeAPI 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
resource ID.
leave type ID.
Header Parameters
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.
1 <= length <= 255ID 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.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v2/locations/string/leave-policies/string"{
"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"
}
}Need help?
developers@vacationtracker.ioChange 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.
Enable or replace a location's leave policy for a leave type
This API method enables the leave policy of a leave type in a location, or replaces it when it is already active. 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. - This is a full replacement, not a merge. `daysPerYear`, `maxRolloverDays`, `quotaUnit`, `isApprovalRequired`, `hasUnlimitedDays`, `hideLeaveType`, `isReasonRequired`, `shortestLeaveInterval` and `toil.enabled` are required, and optional fields you omit are not carried over from the active policy. - Without `accrual`, the policy does not accrue. An accruing `accrual.type` also requires `firstEarningDate`, `periodStart`, `allowAdvanceUsage` and `pauseWhenUserDeactivated`; with `NONE`, `periodStart` is not allowed. - `resetUserOverrides: true` also clears every per-user override of this policy in the location; `broughtForwardExpiration.applyToPastYear: true` applies the expiry to leave rolled over from the previous year. Neither is stored. - Types are strict: a number sent as a string, an unknown field or an invalid JSON body fails validation. 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, or the leave type does not exist or was deleted; `details.resource` is `location` or `leaveType`), and the `Idempotency-Key` codes.