# Customers

Link your customer identity and inspect recorded activity.

Namespace `external_id` by your partner: uniqueness is global. Creating an existing external ID returns an error; creation is not an upsert. See [customer attribution](/build/users/).

[Authentication](/build/authentication/) · [Errors](/build/errors/) · [Amounts and units](/build/units/)


Response examples below come from a local test account. IDs, balances and timestamps are sample data. Replace IDs and credentials with values from your account.


## Create an attributed end-user

`POST /users`


**Access:** `partner:read`.


**SDK methods:** TypeScript `client.users.create(…)`; Python `client.users.create(…)`.



### Request body

Schema: [CreateUserInputDto](/api/partner-models/#createuserinputdto)


### Request example

```bash
curl --fail-with-body -X POST "$THESAUROS_API_BASE/users" \
  -H "Authorization: Bearer $THESAUROS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"external_id":"docs-example-customer","label":"Example customer","wallets":["0x0000000000000000000000000000000000000001"]}'
```

### Response · 201

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [UserRecord](/api/partner-models/#userrecord) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "user",
  "data": {
    "id": "usr_1bb75cc43c5b5ab6",
    "object": "user",
    "external_id": "docs-example-customer",
    "label": "Example customer",
    "email": null,
    "metadata": {},
    "wallets": [
      "0x0000000000000000000000000000000000000001"
    ],
    "status": "active",
    "created_at": "2026-09-07T14:42:45.380Z",
    "updated_at": "2026-09-07T14:42:45.380Z"
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Per-user event ledger (deposits, withdrawals, rebalances, yield accruals)

`GET /users/{id}/ledger`


**Access:** `partner:read`.


**SDK methods:** TypeScript `client.users.ledger(…)`; Python `client.users.ledger(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes |  |

| `limit` | query | `string` | No |  |

### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/users/usr_seed_nova/ledger" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [UserLedgerEvent](/api/partner-models/#userledgerevent)[] | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "list",
  "data": [
    {
      "id": "evt_seed_gamma_dep",
      "object": "ledger_entry",
      "user_id": "usr_seed_nova",
      "position_id": "pos_seed_gamma",
      "asset": "USDC",
      "type": "deposit",
      "amount": 50000,
      "apy": 0.068,
      "vault_id": "vault_morpho_base_usdc",
      "note": "Initial deposit routed to vault",
      "at": "2026-07-15T12:00:00.000Z"
    },
    {
      "id": "evt_seed_alpha_dep",
      "object": "ledger_entry",
      "user_id": "usr_seed_nova",
      "position_id": "pos_seed_alpha",
      "asset": "USDC",
      "type": "deposit",
      "amount": 25000,
      "apy": 0.052,
      "vault_id": "vault_aave_base_usdc",
      "note": "Initial deposit routed to vault",
      "at": "2026-06-20T12:00:00.000Z"
    }
  ]
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).