# Connect your customers

Map your product's customer identity to an attributed Thesauros user and partner account.

Attribution connects a user's records to your partner account. It makes customer activity, account reporting and partner economics accessible in the same integration.

## Create an attributed user

Call `POST /users` with your partner-scoped key. The backend binds the new user to the partner associated with that credential.

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

`external_id` is your customer identifier. Save the returned `data.id` in your backend and use it for subsequent position and ledger lookups.

## Choose a stable identifier

The current backend checks `external_id` across its user store. Namespace the identifier for your product, such as `walletco-customer-42`, and keep it stable across retries. Duplicate creation returns a validation error; it is not an upsert operation.

Before repeating a creation request after an uncertain network result, check the attributed users returned by `GET /partner/users` for your external identifier.

## Wallets and metadata

Wallet inputs must be hexadecimal EVM addresses. The record can also include a label, email and metadata. Send the fields your product needs; the user record is a reporting identity and does not establish ownership of a wallet or permission to transact from it.

## Read the linked activity

- `GET /partner/users` lists your attributed users.
- `GET /partner/user/{id}/positions` returns positions for a user attributed to your partner.
- `GET /users/{id}/ledger` returns that user's recorded events.

Requests for a user outside the calling partner's attribution fail. Preserve that boundary when serving data to your own frontend.