# Account & earnings

## Your profile

`PATCH /v1/me` (scope `account:write`) changes `display_name`, `company_name`, `telegram_username` and `website` — the same fields and checks as the portal's profile page. Send only what changes. `null` or an empty string clears the company name or the website; the Telegram username takes `name`, `@name` or a `t.me/name` link and cannot be removed. Like every `PATCH` it accepts `If-Match` with the `ETag` you last received for your account; without it the last write wins.

`PUT /v1/me/logo` takes `multipart/form-data` with one `file` (PNG, JPEG or WebP, at most 2 MB); we scale it to at most 512 px and remove every metadata block. `DELETE /v1/me/logo` removes it. Both answer with your account. Logos count against the same upload limit as [photos](https://docs.creator-guard.com/photos/#limits).

## Suggest fields from text

`POST /v1/extract` (scope `extract`) reads a profile text, a chat or your notes — `{"text": "…"}`, 20 to 20,000 characters — and suggests lead and listing fields under their API names. **Nothing is stored**: not the text, not the answer — so an `Idempotency-Key` is ignored and a retry simply runs again. Review the suggestions, then send the lead yourself. It works before you have accepted the terms.

Limits: **20 per minute and 200 per day** per account, halved in test mode. If the AI service fails we answer [`502 upstream_failed`](https://docs.creator-guard.com/errors/#upstream_failed); try again later. In [test mode](https://docs.creator-guard.com/test-mode/) the answer is a fixed fictitious example.

## Commissions

A commission is booked for your lead when her placement completes. `GET /v1/commissions` (scope `earnings:read`) lists them, newest first, with the filters `status` (`due`, `paid`, `void`), `created_since` and `lead`; `GET /v1/commissions/{id}` reads one. `?expand=lead` returns a short lead object (`id`, `creator_name`, `creator_ref`, `stage`) in `lead` instead of its id.

| Field | Meaning |
|---|---|
| `fee_total` | The placement fee the agency paid |
| `creator_guard_amount` | Creator Guard's share |
| `your_amount` | Your commission |
| `status` | `due` (we owe it), `paid` (`paid_at` set) or `void` |

Events: `commission.created`, `commission.paid`, `commission.voided` — see [Events](https://docs.creator-guard.com/events/).

## Payout details

`GET /v1/payout-details` (scope `earnings:read`) shows the `method` (`bank`, `paypal` or `crypto`), a **masked** destination such as `DE89 •••• 3000` and when they were last changed; all three are `null` until you save payout details. The API never shows or changes the full details: change them in the portal (**Settings → Payout**), which asks for your second factor.
