> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brand-wallet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a user

> Update a branch-level user's profile, status, branches, or roles.

```http theme={null}
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](/api/authentication).

Payload schema:

```json theme={null}
{
  "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

```bash theme={null}
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](/api/list-users) item.

```json theme={null}
{
  "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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.