Vacation Tracker Docs
REST API v2API referenceLabels

List labels

This API method returns every label in the company, in one response without pagination. Requires `labels:read`. Labels are not limited by the key's data reach, and `userCount` counts users in the whole company.

GET
/v2/labels

Authorization

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

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/labels"
{
  "data": [
    {
      "id": "969f8429-7dc3-48a1-96b1-6049a99dda06",
      "name": "contractor",
      "color": "#FF0000",
      "userCount": 12
    },
    {
      "id": "2c7d9e1f-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "name": "Team B",
      "color": "#00AAFF",
      "userCount": 0
    }
  ]
}
{
  "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": "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

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.

Create a label

This API method creates a label. Requires `labels:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the label to be created and returns it with `201`, or `202 Accepted` with an operation to poll. `name` and `color` are required, non-empty strings; unknown fields fail validation. Assign the label to users with `POST /v2/users/{id}/labels`. Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 INVALID_REQUEST_BODY`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `422 PLAN_LIMIT_REACHED`, and the `Idempotency-Key` codes.