Vacation TrackerDeveloper Docs
REST API v2API referenceUsers

List users

This API method returns a paginated list of users within the key's data reach, with their IDs, names, and basic info. Requires users:read. Each user has the same shape as in API v1.

  • status is matched case-insensitively and defaults to ACTIVE.
  • locations and departments are narrowed to the key's data reach; filters entirely outside it return an empty list.
  • A page can hold fewer than limit users while nextToken is still returned. Keep paginating until nextToken is absent.
  • A key whose owner sees only their own data gets only the key owner, when they match the filters, without nextToken.
  • Each expand value needs the read scope of the resource it embeds: location needs locations:read, department needs departments:read, holidays needs holidays:read. Without it the request fails with 403 INSUFFICIENT_SCOPE, and details.expand names the values that asked for it. locationId and departmentId are returned either way.

Errors: 400 VALIDATION_ERROR (an invalid status, limit or expand; details.fields lists them), 400 INVALID_PAGINATION_TOKEN and 403 INSUFFICIENT_SCOPE (an expand value whose read scope the key does not have).

GET
/v2/users

Authorization

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

Query Parameters

status?string

filter users by status, default is 'ACTIVE'.

Default"ACTIVE"
Value in"ACTIVE" | "INACTIVE" | "DELETED"
locations?array<string>

location IDs used for filtering, sent as a repeated parameter (locations=a&locations=b) or a comma-separated list (locations=a,b). If provided, the API method returns users in one of the provided locations. By default, it returns users in any location within the key's data reach.

departments?array<string>

department IDs used for filtering, sent as a repeated parameter or a comma-separated list. If provided, the API method returns users in one of the provided departments. By default, it returns users in any department within the key's data reach.

labels?array<string>

label IDs used for filtering, sent as a repeated parameter or a comma-separated list. If provided, the API method returns users with one of the provided labels. By default, it returns users with or without labels.

limit?integer

a number of items to return per page, between 1 and 1000, default is 200. The number of returned items might be less than the provided limit even when more pages exist; rely on nextToken. Same semantics as the v1 limit parameter.

Default200
Range1 <= value <= 1000
nextToken?string

The nextToken returned by the previous API call. Send the same filters as in the previous call. Same semantics as the v1 nextToken parameter; a token that was not issued by this API fails with 400 INVALID_PAGINATION_TOKEN.

expand?array<>

a comma-separated list of related resources to include in each user. Options: location (the user's location, requires locations:read), department (the user's department, requires departments:read) and holidays (public holidays for the user's location grouped by year, requires holidays:read). Each value needs the read scope of the resource it embeds.

Value in"location" | "department" | "holidays"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/users?expand=location%2Cdepartment"
{
  "data": [
    {
      "id": "user-cfe5d39b-f1f0-45aa-85cd-ce93e637a262",
      "name": "John Chao",
      "email": "johnchao@chaochao.com",
      "isAdmin": false,
      "locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
      "departmentId": "team-0a21c25e-6925-4a5b-90ee-ecf82096c4f6",
      "status": "ACTIVE",
      "employeeId": "E-1024",
      "startDate": "2022-11-08",
      "endDate": null,
      "labels": [
        {
          "id": "969f8429-7dc3-48a1-96b1-6049a99dda06",
          "name": "contractor",
          "color": "#FF0000"
        }
      ]
    },
    {
      "id": "user-63b17e97-d38b-4586-8498-bb4f5d2e2c14",
      "name": "Ana Petrović",
      "email": "ana@chaochao.com",
      "isAdmin": true,
      "locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
      "departmentId": "team-0a21c25e-6925-4a5b-90ee-ecf82096c4f6",
      "status": "ACTIVE",
      "employeeId": null,
      "startDate": null,
      "endDate": null,
      "labels": []
    }
  ],
  "nextToken": "next-token"
}
{
  "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": "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

Cancel a TOIL request

This API method cancels a TOIL request. Requires toil:write. The acting user (the key owner, or the X-On-Behalf-Of user) can cancel their own TOIL requests, or those of users they manage. The request body is optional; reason is stored as the request's statusReason. It waits for the cancellation and returns the TOIL request with 200, or 202 Accepted with an operation to poll.

Get a user

This API method returns a single user. Requires users:read. Each expand value needs the read scope of the resource it embeds: location needs locations:read, department needs departments:read, holidays needs holidays:read. Without it the request fails with 403 INSUFFICIENT_SCOPE, and details.expand names the values that asked for it.