Update Member

Change a member’s roles, or suspend and reactivate them.

PATCH /api/v1/users/{user_id}

cURL

curl -X PATCH "https://api.wordsmith.ai/api/v1/users/828b17cf-5f09-4edd-bcba-9d1de130a2e6" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "predefined_roles": ["full_user", "admin"],
    "custom_role_ids": ["72f02d30-2d67-40b0-b5cb-859dbb45d485"]
  }'

Response

{
  "id": "828b17cf-5f09-4edd-bcba-9d1de130a2e6",
  "name": "Priya Shah",
  "email": "[e-mail]",
  "kind": "human",
  "is_suspended": false,
  "predefined_roles": ["full_user", "admin"],
  "custom_role_ids": ["72f02d30-2d67-40b0-b5cb-859dbb45d485"],
  "team_ids": ["d38a34b1-d214-438b-96eb-03d864915478"]
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

Changes a member’s roles or suspension. Send only the fields you want to change.

predefined_roles and custom_role_ids each replace the member’s current list. They do not merge. To add a role, read the member with Get Member and send the full list back. The member must end up with at least one role across the two lists.

Suspending a member blocks sign-in, ends their open sessions at once and pauses their schedules. It also unlinks their WhatsApp account. Their files and sharing stay in place. Reactivating restores access and resumes the schedules, but the member must link WhatsApp again. A role change also signs the member out of open sessions, so the new permissions apply straight away.

Customers who provision users through SCIM from their identity provider manage suspension there. A change to is_suspended here is overwritten at the next sync. SCIM does not manage roles, so role changes here persist.

Authentication

Requires an API key, or an OAuth token with directory:admin. The caller must also be an organisation admin, or hold a role with the matching permission. directory:admin is never granted by default. It only narrows what the person who approved it can already do, so a team admin’s token can edit their own teams and nothing else. Admin changes are not available through the MCP server.

Changing roles and suspending are separate permissions. A custom role can grant one without the other.

Wordsmith checks a suspension change before it saves a role change, so a refused request changes nothing.

Path parameters

user_id · string · required

The member’s id.

Body parameters

predefined_roles · string[]

The built-in roles the member should hold: any of viewer, full_user and admin. Replaces the current list. A role your organisation has turned off cannot be assigned.

custom_role_ids · string[]

The custom roles the member should hold, from List Roles. Replaces the current list. Each role you add must exist and be active. Adding a custom role needs a plan that includes custom roles.

is_suspended · boolean

true to suspend the member, false to reactivate them. You cannot suspend yourself, nor the last active member who can assign roles: give someone else that permission first.

confirm_source_disconnection · boolean · default: "false"

Some roles allow connecting external sources, such as a SharePoint or Google Drive library. If the new roles remove the member’s last permission for a source type, Wordsmith disconnects the sources they added and removes the imported copies. The originals at the provider are untouched, and restoring the role does not reconnect them. Set this to true to accept that. Without it, such a change fails with 400 repository_source_disconnection_confirmation_required.

Response

Returns 200 with the updated member.

cURL

curl -X PATCH "https://api.wordsmith.ai/api/v1/users/828b17cf-5f09-4edd-bcba-9d1de130a2e6" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "predefined_roles": ["full_user", "admin"],
    "custom_role_ids": ["72f02d30-2d67-40b0-b5cb-859dbb45d485"]
  }'

Response

{
  "id": "828b17cf-5f09-4edd-bcba-9d1de130a2e6",
  "name": "Priya Shah",
  "email": "[e-mail]",
  "kind": "human",
  "is_suspended": false,
  "predefined_roles": ["full_user", "admin"],
  "custom_role_ids": ["72f02d30-2d67-40b0-b5cb-859dbb45d485"],
  "team_ids": ["d38a34b1-d214-438b-96eb-03d864915478"]
}

Errors

Status	error_code	When
400	invalid_request_body	The body sets none of predefined_roles, custom_role_ids and is_suspended, a field has the wrong type, a predefined_roles value is not viewer, full_user or admin, or a custom_role_ids value is not a role id.
400	bad_request	The change would leave the member with no predefined role and no custom role, assigns a predefined role your organisation turned off, or adds a custom role that does not exist or is inactive. Also returned when is_suspended is true and user_id is the caller. The message says which.
400	no_active_role_assigner	The change would leave your organisation with no active member who can assign roles: a role change that removes the last one’s permission, or suspending them. Give another member that permission first.
400	repository_source_disconnection_confirmation_required	The change would disconnect external sources the member added. Resend with confirm_source_disconnection: true to accept.
403	insufficient_scope	The OAuth token does not hold directory:admin.
403	forbidden	The caller cannot assign roles or cannot suspend members, whichever the request needs. Also returned when adding a custom role on a plan without custom roles.
404	resource_not_found	No member of your organisation has this id, or the caller cannot see the members list.