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).
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
Path Parameters
resource ID.
Query Parameters
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
application/json
curl -X GET "https://example.com/v2/users/string?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"
}
]
}
}{
"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": "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.ioList 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`.
Update a user's profile
This API method changes a user's profile. Requires `users:write`. It waits for the change and returns the user with `200`, or `202 Accepted` with an operation to poll. Send only the fields you want to change; at least one field is required. This method merges your changes with the user's current profile, so fields you do not send are left untouched. Send `null` for `endDate`, `employeeId` or `birthday` to clear it. Who can change what: - `name`, `firstName`, `lastName`, `birthday` and `locale` can be changed by the user themselves, or by an admin or a location admin who manages the user. - `email`, `startDate`, `endDate`, `employeeId`, `isAdmin` and `isNameLocked` require the key owner (or the `X-On-Behalf-Of` user) to be an admin, or a location admin who manages the user. Otherwise the request fails with `403 FORBIDDEN`. - A location admin cannot grant or remove Admin: sending `isAdmin` as a location admin fails with `403 FORBIDDEN`. - When the user's name is locked (`isNameLocked: true`), a name change is ignored unless the same request also sends `isNameLocked: true`. **Warning:** setting `isAdmin` to `false` on a user revokes that user's API keys and webhooks within about 60 seconds. If you demote the key owner, the key you are using is revoked too; the call itself still completes. Location, department, Location Admin role and work week are not profile fields; change them with `PUT /v2/users/{id}/location`, `PUT /v2/users/{id}/department`, `PUT /v2/users/{id}/location-admin` and `PUT /v2/users/{id}/work-week`. Errors: `400 VALIDATION_ERROR` (`details.fields`), `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN` (the acting user may not change these fields), `404 RESOURCE_NOT_FOUND` (the user does not exist or is outside the key's data reach), `409 EMAIL_ALREADY_EXISTS` (the new email is already used by another user), `409 LAST_ADMIN_CANNOT_BE_REMOVED` (`isAdmin: false` for the company's only admin), `422 PLAN_LIMIT_REACHED` (`isAdmin: true` beyond the plan's admin limit), and the `Idempotency-Key` codes.