List automations of a type
This API method returns every automation of the type in the path, active and paused, in one response without pagination. Requires `automations:read`. Automations are company-wide: they are not limited by the key's data reach. Each automation has the fields of its type; `Automation` lists one schema per type (for example `BlackoutPeriodAutomation` for `blackout-period`). `locationIds`, `departmentIds` and `labelIds` are always arrays, and an empty array means the automation applies to everyone; `entitlement-by-role` automations have no filters. Errors: `404 AUTOMATION_TYPE_NOT_FOUND` (`type` is not one of the automation types).
Authorization
bearerAuth automations:readAPI 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: automations:read
Path Parameters
automation type. Any other value returns 404 AUTOMATION_TYPE_NOT_FOUND.
"blackout-period" | "seniority-entitlement" | "entitlement-by-role" | "maximum-users-away" | "probation-period" | "leave-duration-limit" | "leave-request-notice-period"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v2/automations/blackout-period"{
"data": [
{
"id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"type": "blackout-period",
"name": "End of year freeze",
"isActive": true,
"ownerId": "user-63b17e97-d38b-4586-8498-bb4f5d2e2c14",
"createdAt": "2026-09-23T10:00:00.000Z",
"locationIds": [
"location-79c77ac8-e5bf-479f-9488-648a58379ff1"
],
"departmentIds": [],
"labelIds": [],
"leaveTypeIds": [
"leaveType-fcc1e5c5-ba93-479d-bd58-8f860ba10615"
],
"startDate": "2026-12-20",
"endDate": "2026-12-31",
"recurring": true,
"reason": "Year-end closing"
},
{
"id": "5d6e7f80-a1b2-4c3d-9e4f-0a1b2c3d4e5f",
"type": "blackout-period",
"name": "Product launch",
"isActive": false,
"ownerId": "user-0f3a9c1e-6c2b-4a5d-9e7f-1b2c3d4e5f60",
"createdAt": "2026-03-02T08:15:00.000Z",
"locationIds": [],
"departmentIds": [
"team-0a21c25e-6925-4a5b-90ee-ecf82096c4f6"
],
"labelIds": [],
"leaveTypeIds": [
"leaveType-fcc1e5c5-ba93-479d-bd58-8f860ba10615",
"leaveType-88681ca1-4a47-4e4d-bc35-ffff86c0f54e"
],
"startDate": "2026-05-11",
"endDate": "2026-05-15",
"recurring": false,
"reason": ""
}
]
}{
"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": "AUTOMATION_TYPE_NOT_FOUND",
"name": "Automation type not found",
"description": "The automation type was not found.",
"resolution": "Use one of the automation types listed in the API reference.",
"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.ioSet 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. - `amount` is in the company's unit: days, or hours when the company uses hourly accounting. This can differ from the `unit` that `GET /v2/users/{id}/quotas` returns for a leave policy set in the other unit. Up to 365 days or 2920 hours. It is required unless `unlimited` is `true`. - `unlimited: true` gives the user unlimited leave of this type; `amount` is then ignored. - `period` chooses the leave period to change: `current` (default) or `next`. Set `applyToFutureYears: true` to keep this quota in later periods too; by default only the chosen period changes. - `prorate` is allowed only for the user's first leave period (the one containing their start date); sending it for any other period fails with `400 PRORATE_NOT_ALLOWED`. When omitted, the user's prorate setting is left unchanged. The key owner (or `X-On-Behalf-Of` user) must be an admin, or a location admin who manages the user. It waits for the change and returns the user's quotas for the chosen period with `200`, or `202 Accepted` with an operation to poll. Errors: `400 VALIDATION_ERROR` (`details.fields`, including an `amount` above 365 days or 2920 hours), `400 QUOTA_PERIOD_NOT_AVAILABLE` (the requested period does not exist for the user; read `GET /v2/users/{id}/quotas?period=...` to check), `400 PRORATE_NOT_ALLOWED`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the user does not exist or is outside the key's data reach, or the leave type is not active for the user in the chosen period), and the `Idempotency-Key` codes.
Create an automation
This API method creates an automation of the type in the path. Requires `automations:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user, and becomes the automation's owner (`ownerId`). It waits for the automation to be created and returns it with `201`; if that takes longer than the wait window it returns `202 Accepted` with an operation to poll. - Send `name` plus the fields of the type. `CreateAutomationRequest` lists one request schema per type (for example `CreateBlackoutPeriodAutomationRequest` for `blackout-period`). Fields of another type, `id`, `type`, `isActive`, `ownerId` and other unknown fields fail validation. - The automation is created active (`isActive: true`); pause it with `PATCH /v2/automations/{type}/{id}` and `isActive: false`. - `locationIds`, `departmentIds` and `labelIds` limit the users the automation applies to; omitted or empty means everyone. `entitlement-by-role` does not accept them: it applies to the users with the label in `labelId`. - `name`, `reason` and `autoRejectResponse` fail validation when they look like HTML or script. - The acting user must be an approver or an admin; `seniority-entitlement` and `entitlement-by-role` automations can be created only by admins. - The company must have the automation's add-on active; otherwise the request fails with `403 AUTOMATION_ADDON_NOT_ACTIVE`. When the request returns `202`, the same error is reported on the operation. Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 INVALID_REQUEST_BODY`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN` and `403 AUTOMATION_ADMIN_REQUIRED` (the acting user may not create this automation), `403 AUTOMATION_ADDON_NOT_ACTIVE`, `404 AUTOMATION_TYPE_NOT_FOUND` (`type` is not one of the automation types), `409 DUPLICATE_NAME` (another automation already uses the name), and the `Idempotency-Key` codes.