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.

Authorization

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

full display name, leading and trailing spaces are trimmed. Ignored while the name is locked unless isNameLocked true is sent in the same request.

Length1 <= length

firstName?string

first name. When name is sent without firstName and lastName, they are derived from name.

lastName?string

last name

email?string

user email, must be unique in the company. Admin or location admin only.

Formatemail

startDate?string

employment start date in YYYY-MM-DD format. Admin or location admin only.

Match^\d{4}-\d{2}-\d{2}$

Formatdate

endDate?|

employment end date in YYYY-MM-DD format, null to clear it. Admin or location admin only.

Match^\d{4}-\d{2}-\d{2}$

Formatdate

employeeId?|

employee ID, null to clear it. Admin or location admin only.

birthday?|

birthday in YYYY-MM-DD format, null to clear it

Match^\d{4}-\d{2}-\d{2}$

Formatdate

isAdmin?boolean

grant (true) or remove (false) Admin. Admin only; location admins cannot send it. Setting false revokes the user's API keys and webhooks.

isNameLocked?boolean

when true, the user's name is locked, and later name changes are ignored unless they also send isNameLocked true. Admin or location admin only.

locale?string

the user's language for the Vacation Tracker interface and notifications, one of the locale codes Vacation Tracker supports; other values fail validation

Response Body

`application/json`

curl -X PATCH "https://example.com/v2/users/string" \  -H "Content-Type: application/json" \  -d '{    "name": "John Chao",    "employeeId": "E-1024",    "endDate": null  }'

{
  "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"
  }
}

Update a user's profile

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

200application/json

202application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

Key lacks a required scope

Key was revoked

Acting user may not perform the action

The request conflicts with the current state

The default location cannot be deleted

The leave needs more balance than the user has

The leave was already approved, denied or cancelled

TOIL is not enabled for the leave type

The Idempotency-Key was used with a different request

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`