Vacation Tracker Docs
REST API v2API referenceLocations

List locations

This API method returns every location within the key's data reach, in one response without pagination. Requires `locations:read`. Admins see every location; location admins see the locations they manage.

GET
/v2/locations

Authorization

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

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/locations"
{
  "data": [
    {
      "id": "location-6ca89536-be55-42c5-8e52-c5c4215afb9f",
      "name": "Belgrade",
      "timezone": "Europe/Belgrade",
      "isDefault": true,
      "createdAt": "2021-03-15T08:00:00.000Z"
    },
    {
      "id": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
      "name": "Los Angeles",
      "timezone": "America/Los_Angeles",
      "isDefault": false,
      "createdAt": "2022-08-22T15:00:00.000Z"
    }
  ]
}
{
  "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

Delete a department

This API method deletes a department. Requires `departments:write`. No request body. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the deletion and returns `204`, or `202 Accepted` with an operation to poll. - The company's default department can never be deleted: make another department the default first. - A department with sub-departments cannot be deleted: delete or move its sub-departments first. Errors: `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the department does not exist or is outside the key's data reach), `409 DEFAULT_DEPARTMENT_DELETE_FORBIDDEN`, `409 DEPARTMENT_HAS_SUBDEPARTMENTS`, and the `Idempotency-Key` codes.

Create a location

This API method creates a location. Requires `locations:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the location 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. - `name` and `timezone` (an IANA time zone name) are required. - `firstDayOfWeek` defaults to `1` (Monday), `resetQuotas` to `FISCAL_YEAR`, `yearStartMonth` and `yearStartDay` to `1`, `isDefault` to `false` and `userIds` to an empty array. `yearStartDay` must exist in `yearStartMonth` every year, so 29 February is rejected. - `userIds` moves those users into the new location. `isDefault: true` makes it the company's default location. - `workWeek` sets the initial work week, the same as `PUT /v2/locations/{id}/work-week` right after creation. When omitted, the work week is Monday to Friday with the default work hours. - Unknown fields and invalid values fail validation. Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 INVALID_REQUEST_BODY`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `403 WORK_HOURS_LIMIT_REACHED` (`workWeek.workHours` needs a plan with custom work hours), `409 DUPLICATE_NAME` (another location already uses the name), `422 UNKNOWN_USER_IDS`, `422 PLAN_LIMIT_REACHED`, and the `Idempotency-Key` codes.