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

# The User object

> Data model and reference for customer end-user records attached to companies in your workspace.

A user is an end-user (or agent identity) associated with a company. Users hold identity fields (`name`, `email`, `walletAddress`, `externalId`, `clerkUserId`) and traits. They are normally created automatically through `identify()` and the Events API — the explicit REST surface below is provided for management and reconciliation.

## User object

```json theme={null}
{
  "id": "us_abc123",
  "name": "Jane Doe",
  "email": "jane@acme.com",
  "walletAddress": "0xabc...",
  "clerkUserId": "user_2xyz",
  "externalId": "user_123",
  "companyId": "cm_abc123",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "lastSeenAt": "2026-09-17T10:00:00.000Z"
}
```

## List users

`GET /api/v1/users`

Auth: legacy `api_…` key or dashboard session.

| Query       | Type   | Description                                                          |
| ----------- | ------ | -------------------------------------------------------------------- |
| `limit`     | number | Results per page, max 200, default 50                                |
| `cursor`    | string | Pagination cursor (previous `nextCursor`)                            |
| `companyId` | string | Filter users for a company                                           |
| `search`    | string | Case-insensitive search across name, email, wallet, and company name |

```bash theme={null}
curl -X GET "https://api.arcenpay.com/api/v1/users?limit=50&search=acme" \
  -H "Authorization: Bearer api_xxxxxxxx"
```

```json theme={null}
{
  "data": [ { "id": "us_abc123", "name": "Jane Doe", "email": "jane@acme.com", "walletAddress": "0xabc...", "companyId": "cm_abc123", "createdAt": "…", "lastSeenAt": "…" } ],
  "count": 1,
  "nextCursor": null
}
```

## Create a user

`POST /api/v1/users`

Auth: legacy `api_…` key or dashboard session.

<ParamField body="companyId" type="string" required>
  The company to attach the user to (`cm_…`). Must already exist in your team and environment.
</ParamField>

<ParamField body="id" type="string">
  Your system's external user ID (max 64 chars). Stored as `externalId`.
</ParamField>

<ParamField body="wallet" type="string">
  User wallet address.
</ParamField>

<ParamField body="clerk_user_id" type="string">
  Optional Clerk user ID.
</ParamField>

<ParamField body="name" type="string">
  Display name (max 128 chars).
</ParamField>

<ParamField body="email" type="string">
  Email address (validated).
</ParamField>

<ParamField body="traits" type="object">
  Arbitrary key-value metadata.
</ParamField>

```json theme={null}
{
  "companyId": "cm_abc123",
  "id": "user_456",
  "wallet": "0xabc...",
  "email": "jane@acme.com",
  "name": "Jane Doe"
}
```

Returns `201` with the created user. A duplicate match returns `409` with the existing `userId`.

<Note>
  **Prefer `identify()` over direct user creation.** `POST /api/v1/access-tokens` (the Node SDK's `identify()`) upserts both company and user in one call and returns the embed token your frontend needs. The direct users endpoint is for bulk imports and reconciliation.
</Note>

## Related

* [Create an access token](/api-reference/credentials/create-an-access-token-identify) — `identify()` creates users implicitly
* [The Event object](/api/events) — identify events upsert users
* [The Company object](/api/companies) — the parent entity