users_users_update

Tool

users_users_update

Update an end user's profile, status flags and metadata bags.

Update an end user's profile, status flags and metadata bags. Only the fields you pass change. A metadata field REPLACES that whole bag — send the full object you want stored. Write matrix in this phase: the management plane writes all three bags (public: end-user readable and may flow into the JWT; private: management plane only; unsafe: end-user writable later and never authoritative for authorization). `stage` moves the person along the funnel and publishes `users/user.stage-changed`; a patch that changes ONLY the stage deliberately does not also publish `users/user.updated`, so a workflow that writes stages does not wake itself. `tags` REPLACES the whole list. `kind` is NOT editable here and is refused with `kind_not_updatable`: a contact becomes an account only by proving an address.

Behavior

HTTP: PATCH /users/users/:userId

Arguments

Name	Type	Required	Description
name	string	—	The user's display name. Pass null to clear.
tags	string	—	REPLACES the whole tag list — send every tag you want stored, not just the new ones. Trimmed, lowercased and de-duplicated on write.
stage	string	—	Move the person to this relationship stage. A real change publishes `users/user.stage-changed`; a patch that changes ONLY the stage deliberately does not also publish `users/user.updated`, so a workflow that writes stages does not wake itself.
userId	string	•	The user to update.
imageUrl	string	—	URL of the user's avatar image. Pass null to clear.
waitlisted	boolean	—	Whether the user is still a waitlist signup.
lockedUntil	string	—	ISO-8601 timestamp of a temporary, self-healing lockout — the failed-attempt ceiling sets it and it expires on its own. Pass null to unlock the account immediately (audited as `user.unlocked`).
requiresReset	boolean	—	Whether the user must reset their password before signing in.
publicMetadata	object	—	REPLACES the whole public metadata bag. Management-plane write, end-user read.
unsafeMetadata	object	—	REPLACES the whole unsafe metadata bag. End-user writable in a later phase; never authoritative.
privateMetadata	object	—	REPLACES the whole private metadata bag. Management plane only.

Response

Field	Type	Always	Description
id	string	•	Id of this end user. Pass it to any users_users_* tool.
kind	string	•	What kind of person this row is: 'account' (can sign in) or 'contact' (known to the Product, no credential, never signed in). A contact is hidden from the default users_users_list view and is never counted as a retained user.
name	string	•	The user's display name. Null when nobody set one.
tags	array	•	Free labels on this person, stored trimmed, lowercased and de-duplicated.
stage	string	•	The relationship stage, in funnel order: new, contacted, replied, engaged, converted, lost. A real change publishes `users/user.stage-changed`.
bannedAt	string	•	When the user was banned (ISO 8601). Null while they are not banned.
erasedAt	string	•	When this user's personal data was purged for good (ISO 8601). Null while it is intact.
imageUrl	string	•	URL of the user's avatar. Null when there is none.
testUser	boolean	•	Whether this is a test fixture — excluded from metering and from the default listing.
createdAt	string	•	When the user was created (ISO 8601).
deletedAt	string	•	When the user was soft-deleted (ISO 8601). Null while the account is live.
productId	string	•	Product this user belongs to. Never an input — it comes from the calling identity.
updatedAt	string	•	When the user was last changed (ISO 8601).
mergedFrom	string	•	Set when you asked for an id that was merged into this account — it is the id you asked for, and this is the row it now lives in. Null on every ordinary read.
waitlisted	boolean	•	Whether this user is still on the waitlist and cannot sign in yet.
identifiers	array	•	Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
lastTouchAt	string	•	When this person was last touched — the most recent logged interaction (ISO 8601). Null when nobody has logged one. This is when the interaction HAPPENED, not when it was logged.
lockedUntil	string	•	When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
lastSignInAt	string	•	When the user last signed in (ISO 8601). Null if they never have.
primaryEmail	string	•	The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
requiresReset	boolean	•	Whether the user must set a new password at their next sign-in.
publicMetadata	object	•	Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
unsafeMetadata	object	•	Metadata the end user may write themselves. Treat it as untrusted.
privateMetadata	object	•	Metadata for the management plane only. Never reaches the end user or a token.
mergedIntoUserId	string	•	The user this person was merged INTO, when they were merged. Null for everybody else — follow it to find where their records went.
primaryIdentifierId	string	•	Id of the primary identifier row. Null when there is no primary identifier.
emailChangeLockedUntil	string	•	Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.

Try it

Update an end user's profile, status flags and metadata bags.

When to use

Example

Ask your agent something like this:

Update an end user's profile, status flags and metadata bags.

The agent will invoke users_users_update with these arguments:

{
  "userId": "<userId>"
}