Deactivate a user
This API method deactivates an `ACTIVE` user: they can no longer sign in or request leave, and they stop taking a seat. Requires `users:write`. No request body. The key owner (or `X-On-Behalf-Of` user) must be an admin, or a location admin who manages the user. It waits for the change and returns the user with `status: INACTIVE` and `200`, or `202 Accepted` with an operation to poll. Use `POST /v2/users/{id}/activate` to undo it. The API cannot delete users. **Warning:** deactivation revokes the user's API keys and webhooks within about 60 seconds. If you deactivate the key owner, the key you are using is revoked too; the call itself still completes. Errors: `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the user does not exist or is outside the key's data reach), and the `Idempotency-Key` codes.
Authorization
bearerAuth users:writeAPI 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:write
Path Parameters
resource ID.
Header Parameters
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.
1 <= length <= 255ID 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
application/json
curl -X POST "https://example.com/v2/users/string/deactivate"{
"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"
}
]
}
}{
"operation": {
"id": "pa_3f1c2b9e-8a47-4d5e-9c61-2b7f0e4a1d93",
"status": "PENDING",
"url": "/v2/operations/pa_3f1c2b9e-8a47-4d5e-9c61-2b7f0e4a1d93"
}
}{
"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.ioActivate a user
This API method activates an `INACTIVE` user, so they can sign in and request leave again. Requires `users:write`. No request body. The key owner (or `X-On-Behalf-Of` user) must be an admin, or a location admin who manages the user. It waits for the change and returns the user with `status: ACTIVE` and `200`, or `202 Accepted` with an operation to poll. Activation takes a seat on the company's subscription. When no seat is free it fails with `409 USER_SEAT_LIMIT_REACHED`; free a seat by deactivating another user or add seats in the Vacation Tracker dashboard, then retry. Errors: `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the user does not exist or is outside the key's data reach), `409 USER_SEAT_LIMIT_REACHED`, and the `Idempotency-Key` codes.
Remove a user's Location Admin role
This API method removes the Location Admin role from a user for all the locations they manage. Requires `users:write`. No request body. The user keeps their regular role (and Admin, if they have it). The key owner (or `X-On-Behalf-Of` user) must be an admin, or a location admin who manages all of the user's managed locations. It waits for the change and returns `204`, or `202 Accepted` with an operation to poll. **Warning:** removing the role reduces the user's reach, so their API keys and webhooks are revoked within about 60 seconds. Errors: `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the user does not exist or is outside the key's data reach), `404 ROLE_NOT_FOUND` (the Location Admin role cannot be found), `409 LAST_ADMIN_CANNOT_BE_REMOVED` (the change would leave the company without an admin), and the `Idempotency-Key` codes.