> ## 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.

# Create a user

> Create a branch-level user (cashier or branch manager) in the organization your access token is scoped to.

```http theme={null}
POST $BASE_URL/v1/users
```

**Creates a user in your access token's organization. Roles are given as role codes; integrations can assign only the branch-level roles `branch_user` and `branch_manager`.**

> **Auth:** `Authorization: Bearer <accessToken>` — an organization-scoped token from [Authentication](/api/authentication).

Payload schema:

```json theme={null}
{
  "fullname": "Jane Cashier",                      // required
  "email": "jane@example.com",                     // required — globally unique
  "password": "s3cret",                            // required, min 5 chars
  "phone": "+905321112233",                        // optional
  "status": 1,                                      // optional, defaults to 1
  "roles": ["branch_user" | "branch_manager"],     // optional — role codes
  "branch": "377ec3ad-28c8-4008-b3df-005a434dcf8b",       // optional — branch id
  "authBranches": ["377ec3ad-28c8-4008-b3df-005a434dcf8b"], // optional — branch ids
  "opaqueId": "pos-user-7"                         // optional — your own user id
}
```

### Body

| Field | Type | Description |
| - | - | - |
| `fullname` | string | Required. |
| `email` | string | Required. Globally unique across BrandWallet — `user_already_exists` (400) on conflict. |
| `password` | string | Required, minimum 5 characters. Never returned by any endpoint. |
| `phone` | string | Optional. Normalized to E.164; an unparseable number is silently dropped (the user is created without a phone). |
| `status` | number | Optional, defaults to `1` (active). |
| `roles` | string\[] | Optional. Role codes. Assignable codes: `branch_user`, `branch_manager` — any other code returns `role_not_allowed` (400). Omitted = user is created without roles. |
| `branch` | string | Optional. The branch the user belongs to. |
| `authBranches` | string\[] | Optional. Branches the user is authorized for. |
| `opaqueId` | string | Optional. Your own system's user id. |

> The user is always created in your token's organization — an organization cannot be passed in the body. `system_admin` and `api_user` roles can never be assigned through the API.

### Example

```bash theme={null}
curl --request POST \
  --url "$BASE_URL/v1/users" \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "fullname": "Jane Cashier",
    "email": "jane@example.com",
    "password": "s3cret",
    "roles": ["branch_user"],
    "branch": "377ec3ad-28c8-4008-b3df-005a434dcf8b",
    "opaqueId": "pos-user-7"
  }'
```

### Response

Returns **201** with the created user — the same shape as a [List users](/api/list-users) item.

```json theme={null}
{
  "id": "fa000708-10f6-47ea-a35d-d3e1acbd4be5",
  "fullname": "Jane Cashier",
  "email": "jane@example.com",
  "status": 1,
  "organization": "ca5495d7-36ee-4f6d-8149-0dd082f7c745",
  "branch": "377ec3ad-28c8-4008-b3df-005a434dcf8b",
  "authBranches": [],
  "roles": [
    { "id": "e5e94c4a-7ab7-4568-bf5d-4ea61c2300af", "code": "branch_user", "name": "Branch User" }
  ],
  "opaqueId": "pos-user-7",
  "createdAt": "2026-10-08T12:00:00.000Z",
  "updatedAt": "2026-10-08T12:00:00.000Z"
}
```

Notes:

* Optional fields that have no value are omitted from the response — you will not receive `null`.
* `roles` in the response contains only public-facing roles.
* Credentials are never returned.
* Use [POST /v1/users/:id](/api/update-user) to change the user later and [DELETE /v1/users/:id](/api/delete-user) to remove them.


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