Vacation Tracker Docs
REST API v2API referenceLocations

Delete a location

This API method deletes a location. Requires `locations: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 location can never be deleted: make another location the default first. Deleting any other location moves all of its users to the default location and deletes the location's holidays. 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), `409 DEFAULT_LOCATION_DELETE_FORBIDDEN`, and the `Idempotency-Key` codes.

DELETE
/v2/locations/{id}

Authorization

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

Path Parameters

id*string

resource 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.

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"
{
  "operation": {
    "id": "pa_3f1c2b9e-8a47-4d5e-9c61-2b7f0e4a1d93",
    "status": "PENDING",
    "url": "/v2/operations/pa_3f1c2b9e-8a47-4d5e-9c61-2b7f0e4a1d93"
  }
}
Empty
{
  "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.io

Update a location

This API method changes a location. Requires `locations:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the change and returns the location with `200`, or `202 Accepted` with an operation to poll. Send only the fields you want to change; at least one field is required. Your changes are merged with the location's current state and members, so everything you do not send is kept: - `userIds`, when sent, **replaces the full membership**. Any user currently in this location whose ID is missing from the list is moved to the company's default location. - `isDefault: false` for the current default location fails with `409 DEFAULT_LOCATION_UNSET_FORBIDDEN`; set another location's `isDefault` to `true` instead. - `yearStartMonth` and `yearStartDay` are checked together with the current values: the day must exist in the month every year. - When brought-forward days expire is set per leave policy, not on the location (see the leave policy `broughtForwardExpiration`). Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 INVALID_REQUEST_BODY`, `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), `409 DEFAULT_LOCATION_UNSET_FORBIDDEN`, `409 DUPLICATE_NAME`, `422 UNKNOWN_USER_IDS`, and the `Idempotency-Key` codes.

Get a location's work week

This API method returns the working days and work hours of a location. Requires `locations:read`. `workHours` lists only the days with custom work hours and is left out when there are none. Errors: `404 RESOURCE_NOT_FOUND` (the location does not exist or is outside the key's data reach, or it has no stored work week yet).