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`. Errors: `400 VALIDATION_ERROR` (an invalid `status`, `limit` or `expand`; `details.fields` lists them) and `400 INVALID_PAGINATION_TOKEN`.
Authorization
bearerAuth users: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: users:read
Query Parameters
filter users by status, default is 'ACTIVE'.
"ACTIVE""ACTIVE" | "INACTIVE" | "DELETED"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.
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.
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.
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.
2001 <= value <= 1000The 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.
a comma-separated list of related resources to include in each user.
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.ioCancel 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. Errors: `400 VALIDATION_ERROR` (`details.fields`), `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the TOIL request does not exist or is outside the key's data reach), `422 TOIL_REQUEST_NOT_OPEN` (the request can no longer be cancelled), and the `Idempotency-Key` codes.
Get a user
This API method returns a single user. Requires `users:read`. Errors: `400 VALIDATION_ERROR` (an unknown `expand` value) and `404 RESOURCE_NOT_FOUND` (the user does not exist or is outside the key's data reach).