Update a user - BrandWallet

POST $BASE_URL/v1/users/:id

Updates a user of your access token’s organization. All fields are optional; only the fields you send change. Integrations can update only users whose roles are branch-level (branch_user / branch_manager).

Auth: Authorization: Bearer <accessToken> — an organization-scoped token from Authentication.

Payload schema:

{
  "fullname": "Jane C.",
  "phone": "+905321112233",
  "status": 1 | 0 | -1,                            // -1 archives the user
  "rolesToAdd": ["branch_manager"],                // role codes to add
  "rolesToRemove": ["branch_user"],                // role codes to remove
  "branch": "377ec3ad-28c8-4008-b3df-005a434dcf8b",
  "authBranches": ["377ec3ad-28c8-4008-b3df-005a434dcf8b"],
  "opaqueId": "pos-user-7"
}

Path parameters

Parameter	Type	Description
`id`	string	Required. The user’s id (UUID).

Body

Field	Type	Description
`fullname`	string	Optional.
`phone`	string	Optional.
`status`	number	Optional. `1` = active.
`rolesToAdd`	string[]	Optional. Role codes to add. Assignable codes: `branch_user`, `branch_manager` — any other code returns `role_not_allowed` (400).
`rolesToRemove`	string[]	Optional. Role codes to remove. Same code restriction.
`branch`	string	Optional. Branch id.
`authBranches`	string[]	Optional. Branch ids — the full array replaces the existing one.
`opaqueId`	string	Optional. Your own system’s user id.

The user’s email cannot be changed through this endpoint, and the user cannot be moved to another organization.

Example

curl --request POST \
  --url "$BASE_URL/v1/users/fa000708-10f6-47ea-a35d-d3e1acbd4be5" \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "fullname": "Jane C.",
    "rolesToAdd": ["branch_manager"],
    "rolesToRemove": ["branch_user"]
  }'

Response

Returns 201 with the updated user — the same shape as a List users item.

{
  "id": "fa000708-10f6-47ea-a35d-d3e1acbd4be5",
  "fullname": "Jane C.",
  "email": "jane@example.com",
  "status": 1,
  "organization": "ca5495d7-36ee-4f6d-8149-0dd082f7c745",
  "branch": "377ec3ad-28c8-4008-b3df-005a434dcf8b",
  "authBranches": [],
  "roles": [
    { "id": "8f2f6c1e-0000-4f8b-9c0d-7e5a1b2c3d4e", "code": "branch_manager", "name": "Branch Manager" }
  ],
  "opaqueId": "pos-user-7",
  "createdAt": "2026-10-08T12:00:00.000Z",
  "updatedAt": "2026-10-08T12:30:00.000Z"
}

Notes:

Updating a user that does not exist returns entity_not_found (400); a user outside your organization returns auth_error (400).
Updating a user whose roles are not branch-level returns user_not_updatable (400); API users return api_user_not_updatable (400).
system_admin and api_user roles can never be assigned through the API (role_not_allowed, 400).
Optional fields that have no value are omitted from the response — you will not receive null.

Last modified on October 8, 2026