Create a user - BrandWallet

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.

Payload schema:

{
  "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

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

{
  "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 to change the user later and DELETE /v1/users/:id to remove them.

Last modified on October 8, 2026