Update User

PATCH/users/:id

Caller

Requires write:users and an active, verified API-key owner with permission to manage the requested users.

Key	Supported users
Company-scoped	Hirer company and project users
Agency-scoped	Agency Admin and Agency Staff users

Summary

Updates an existing user by ObjectId or reference. Omitted fields are preserved. Every existing company or agency membership must be within the key scope and manageable by the key owner. Project-admin callers must also manage every assigned project.

Deactivation revokes the user's API keys and removes them from approval routes.

The role, companyRoleId and companyRoleCompanyId fields are not accepted. Base roles and custom role assignments cannot be changed through this endpoint. Use Update User Membership to add or remove memberships. Use the portal for your own account or role changes. Email and activation changes may be rejected for users connected to multiple agencies.

Path Parameters

Name	Type	Required	Description
id	string	Yes	User ObjectId or reference

Request Fields

Field	Type	Required	Description
firstName	string	No	First name
lastName	string	No	Last name
email	string	No	Valid, unique email; hirer SSO domain and exception rules apply
phone	string	No	Phone number
countryCode	string	No	Telephone dialling code
jobTitle	string	No	Job title
tags	object[]	No	Project-user tags: each item contains a tag ObjectId and an optional company ObjectId; mandatory-tag rules apply
approvalStages	object[]	No	One item with a company ObjectId and integer stage (1–4); the stage must be configured for that company and the role must be projectApprover
active	boolean	No	Activate or deactivate the account; strings are rejected
autoAssignNewProjects	boolean	No	Automatically assign the user to new projects in the specified company
companyId	string	When updating tags or automatic project assignment	Assigned company ObjectId within the key scope; required when updating tags or automatic project assignment

Tag updates replace only the selected company's tags. If a tag includes a company, it must match companyId; mismatches are rejected. Tags apply to project users. Invitations cannot be resent through this endpoint.

Example

{
  "jobTitle": "Senior Buyer",
  "active": false
}

Response

Returns HTTP 200 with a public profile. Passwords, reset tokens, MFA credentials, preferences and private account settings are excluded.

Field	Type	Description
success	boolean	true
data	object	Show child attributes id (string): user ObjectId reference (string): user reference firstName (string): first name lastName (string): last name email (string): email phone (string, optional): phone number countryCode (string, optional): dialling code jobTitle (string, optional): job title role (string): base role active (boolean): active status verified (boolean): verification status
meta	object	Empty object

Errors

HTTP status	Cause
400	Invalid or unsupported fields, duplicate email, SSO-domain rejection, or workflow restriction
401	Missing or invalid API key
403	Missing write:users, inactive or unverified owner, or insufficient management permissions
404	User or membership not found within the key scope
429	Rate limit exceeded
500	User write or invitation delivery failed