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

# List all users

> Returns paginated users for the organization your access token is scoped to, with optional filters on email, phone, status, role, and branch.

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

**Returns the users (team members and API users) of your access token's organization, newest first, in the standard [list envelope](/api/pagination) (`data` + `meta`). Deleted users are excluded.**

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

### Query parameters

`limit` (default `50`, max `250`) and `cursor` follow the shared pagination contract — see [Pagination & filtering](/api/pagination).

### Filterable fields

Filters combine with each other (and with the organization scope) using AND.

| Field | Type | Match | Description |
| - | - | - | - |
| `f[status]` | number | exact / IN | Status code (`1` = active). Comma = IN (`f[status]=1,-1`). |
| `f[email]` | string | contains (min 3) | Case-insensitive substring match on the user's email. |
| `f[phone]` | string | contains (min 3) | Case-insensitive substring match on the user's phone. |
| `f[roles]` | string | exact / IN | Role id — users holding that role. |
| `f[branch]` | string | exact / IN | Branch id — users assigned to that branch. |
| `f[opaqueId]` | string | exact / IN | External identifier assigned to the user. Comma = IN. |

> In `contains` filters the comma is searched literally, and values below the minimum length return `invalid_filter_value` (400). Filtering on any other field returns `invalid_filter_field` (400).

### Example

```bash theme={null}
curl --request GET \
  --url "$BASE_URL/v1/users?f%5Bstatus%5D=1&limit=50" \
  --header 'Authorization: Bearer <accessToken>'
```

### Response

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

Notes:

* `meta.total` is the total record count for the current filter, independent of paging position; `meta.cursor` is the paging token for the next page and is omitted on the last page.
* `organization`, `branch` and `authBranches` are plain id strings.
* Optional fields that have no value (`phone`, `branch`, `authBranches`, `opaqueId`) are omitted — you will not receive `null`.
* `roles` contains only public-facing roles; internal system roles are not listed, so an empty `roles` array does not mean the user has no role.
* Credentials and internal account settings are never returned.
* Use [GET /v1/users/:id](/api/get-user) to load a single user.


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