# Customers

Link your customer identity and inspect recorded activity.

This is the simulated Earn API. Position creation and withdrawal change sandbox records; they do not sign a wallet transaction.


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


## Create an end-user

`POST /users`


Maps one of your customers to a Thesauros user via external_id (unique) and links their wallets.


### Parameters

| Name | Location | Type | Required | Description |

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

| `Idempotency-Key` | header | `string` | No | Client-generated key. Retries with the same key replay the original response. |


### Request body

Schema: [CreateUserRequest](/api/sandbox-models/#createuserrequest)


### Response · 201

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [User](/api/sandbox-models/#user) | Yes |   |
| `meta` | `object` | No |   |


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


## List end-users

`GET /users`


### Parameters

| Name | Location | Type | Required | Description |

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

| `status` | query | `"active"`, `"disabled"` | No | Filter by status |

| `wallet` | query | `string` | No | Filter by linked wallet |

| `limit` | query | `integer` | No | Page size (1-500, default 100) |

| `cursor` | query | `string` | No | Opaque cursor returned as meta.next_cursor |

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"list"` | Yes |   |
| `data` | [User](/api/sandbox-models/#user)[] | Yes |   |
| `meta` | [ListMeta](/api/sandbox-models/#listmeta) | Yes |   |


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


## Get an end-user

`GET /users/{id}`


### Parameters

| Name | Location | Type | Required | Description |

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

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

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [User](/api/sandbox-models/#user) | Yes |   |
| `meta` | `object` | No |   |


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


## Update an end-user

`PATCH /users/{id}`


### Parameters

| Name | Location | Type | Required | Description |

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

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


### Request body

Schema: [UpdateUserRequest](/api/sandbox-models/#updateuserrequest)


### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [User](/api/sandbox-models/#user) | Yes |   |
| `meta` | `object` | No |   |


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


## A user's positions

`GET /users/{id}/positions`


### Parameters

| Name | Location | Type | Required | Description |

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

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

| `limit` | query | `integer` | No | Page size (1-500, default 100) |

| `cursor` | query | `string` | No | Opaque cursor returned as meta.next_cursor |

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"list"` | Yes |   |
| `data` | [Position](/api/sandbox-models/#position)[] | Yes |   |
| `meta` | [ListMeta](/api/sandbox-models/#listmeta) | Yes |   |


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


## A user's reconciliation ledger

`GET /users/{id}/ledger`


### Parameters

| Name | Location | Type | Required | Description |

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

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

| `asset` | query | `"USDC"`, `"USDT"` | No | Filter by asset |

| `type` | query | `"deposit"`, `"withdraw"`, `"close"`, `"accrual"` | No | Filter by entry type |

| `limit` | query | `integer` | No | Page size (1-500, default 100) |

| `cursor` | query | `string` | No | Opaque cursor returned as meta.next_cursor |

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"list"` | Yes |   |
| `data` | [LedgerEntry](/api/sandbox-models/#ledgerentry)[] | Yes |   |
| `meta` | [ListMeta](/api/sandbox-models/#listmeta) | Yes |   |


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