# Listing & review

Her **listing** is what agencies see once she is approved: age, origin, languages, content, availability and the deal. A new lead starts as a `draft`; you complete the listing, she confirms consent and 18+ herself, and you submit her for review.

| Request | Does |
|---|---|
| `GET /v1/leads/{id}/listing` | Her listing. |
| `PATCH /v1/leads/{id}/listing` | Change listing fields and your fee. |
| `POST /v1/leads/{id}/consent-link` | Her personal consent link. |
| `GET /v1/leads/{id}/confirmations` | Consent, 18+ and login state. |
| `POST /v1/leads/{id}/submit-for-review` | Draft → in review. |
| `GET /v1/leads/{id}/timeline` | Milestones. |
| `GET /v1/leads/{id}/earnings` | Your earnings from her (scope `earnings:read`). |

## Change the listing

curl:

```bash
curl -X PATCH https://api.creator-guard.com/v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy/listing \
  -H "Authorization: Bearer $CG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "age": 24,
    "gender": "female",
    "origin_country": "Germany",
    "languages": ["German", "English"],
    "english_level": 7,
    "content_types": ["Livestreams"],
    "placement_fee": {
      "amount_minor": 150000,
      "currency": "USD"
    }
  }'
```

JavaScript:

```js
// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
  "age": 24,
  "gender": "female",
  "origin_country": "Germany",
  "languages": ["German", "English"],
  "english_level": 7,
  "content_types": ["Livestreams"],
  "placement_fee": {
    "amount_minor": 150000,
    "currency": "USD"
  }
};

const res = await fetch('https://api.creator-guard.com/v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy/listing', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.CG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);
```

Python:

```python
# pip install requests
import os
import uuid
import requests

body = {
    "age": 24,
    "gender": "female",
    "origin_country": "Germany",
    "languages": ["German", "English"],
    "english_level": 7,
    "content_types": ["Livestreams"],
    "placement_fee": {
        "amount_minor": 150000,
        "currency": "USD",
    },
}

res = requests.request(
    "PATCH",
    "https://api.creator-guard.com/v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy/listing",
    headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
    json=body,
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)
```

Send only what changes. `null` clears a value, `[]` empties a list (`languages`, `content_types` and `blocked_countries` cannot be `null`; `social_preferences` is emptied with `{}`).

- Listing fields can change while the listing is not live (`next_actions.can_edit_listing`); afterwards [`409 listing_locked`](https://docs.creator-guard.com/errors/#listing_locked).
- The fee can change while the listing is a draft or in review (`next_actions.can_edit_fee`). On a withdrawn listing it answers [`409 invalid_state`](https://docs.creator-guard.com/errors/#invalid_state) with `error.current_state` `withdrawn`.

`GET` and `PATCH …/listing` answer with the listing's own `ETag`. Send it as `If-Match` to make the change race-safe, exactly as for [leads](https://docs.creator-guard.com/leads/#concurrent-changes): a stale value → [`412 precondition_failed`](https://docs.creator-guard.com/errors/#precondition_failed), read again and retry.

## Fields

Every field is optional. Lists take at most 20 `languages`, 30 `content_types` and 250 `blocked_countries`. Types and limits field by field: [ListingPatch](https://docs.creator-guard.com/reference/#schema-ListingPatch).

| Group | Fields |
|---|---|
| Profile | `age` (18–99, below 18 → [`age_below_18`](https://docs.creator-guard.com/errors/#age_below_18)), `gender`, `origin_country`, `languages` ([pick-list values](https://docs.creator-guard.com/leads/#pick-list-values)), `english_level` (1–10) |
| Content | `content_types` ([pick-list values](https://docs.creator-guard.com/leads/#pick-list-values)), `content_freetext`, `content_ready`, `scripts_ready` |
| OnlyFans | `has_of_account`, `of_verified`, `of_current_earnings` (USD per month), `account_access` |
| Social | `social_status`, `social_preferences` (platform → `true`/`false`), `tiktok_ok`, `blocked_countries`, `device` |
| Availability | `start_availability` (`now` or `date`), `start_date`, `availability_hours_per_week`, `availability_hours_per_day` |
| Deal | `compensation_model` (`revenue_share` or `fixed`), `creator_share_percent`, `fixed_salary`, `salary_period` |
| Fee | `placement_fee`: money, e.g. `{"amount_minor": 150000, "currency": "USD"}` = 1,500.00 USD (USD, EUR or GBP) |
| Public note | `notes_public`, shown to agencies with the listing |

Upload photos with `POST /v1/leads/{id}/photos` or in the portal — see [Photos](https://docs.creator-guard.com/photos/). `listing.photo_count` on the lead shows how many she has.

## Her confirmations

Two confirmations must come from the creator herself: that she is **18 or older**, and her **consent** to be introduced to agencies. `POST /v1/leads/{id}/consent-link` returns her personal page:

```json
{
  "object": "consent_link",
  "lead": "lead_hz5ikyc3pnhkrhlb6p7elkx2qy",
  "url": "https://app.creator-guard.com/creator-consent/…",
  "expires_at": "2026-11-08T08:00:00Z"
}
```

A new lead already comes with its link: `consent.url` in the `201` of `POST /v1/leads`. We store links only as hashes, so a link is shown once — a `200` of `POST /v1/leads`, `GET /v1/leads/{id}` and an `Idempotency-Key` replay answer `consent.url: null` (with the current `expires_at`); after her data was erased, both are `null`.

Send it to her. Each call makes a **new** link, valid at least 30 days from now, and the link you sent before can then only be used to withdraw consent — call it only when you are about to send her the link; a revoked consent still gets a link, so she can grant it again. Never open it and confirm on her behalf. After her data was erased at her request, the answer is [`409 invalid_state`](https://docs.creator-guard.com/errors/#invalid_state) with `error.current_state` `anonymized`.

`GET /v1/leads/{id}/confirmations` shows `consent.status` (`pending`, `granted`, `revoked`), `age_confirmation.status` (`missing`, `confirmed`, `declined`) and `creator_login.status` (`none`, `active`), with dates — never her IP address or browser.

## Submit for review

When `next_actions.can_submit_for_review` is `true`, `POST /v1/leads/{id}/submit-for-review` moves her to `in_review` and answers with the lead. With blockers left the answer is [`422 not_ready_for_review`](https://docs.creator-guard.com/errors/#not_ready_for_review) with `error.blockers`; a lead that is not a draft answers [`409 invalid_state`](https://docs.creator-guard.com/errors/#invalid_state) with `error.current_state`.

`next_actions.blockers` lists what still keeps her off the marketplace:

| Blocker | Fix |
|---|---|
| `age_missing`, `country_missing`, `languages_missing`, `content_types_missing` | Set the listing field. |
| `photos_missing` | Three photos: [`POST /v1/leads/{id}/photos`](https://docs.creator-guard.com/photos/) or the portal. |
| `consent_missing`, `age_confirmation_missing` | She confirms through her consent link. |
| `fee_missing` | Set `placement_fee`. Without it she cannot be submitted for review or go live. Leads our team added for your account never show it. |

New blocker values may be added; show unknown ones as text. After submitting, the lead fields are locked (`external_id` stays changeable); listing fields and the fee can still change until she goes live.

## Timeline and earnings

`GET /v1/leads/{id}/timeline` lists milestones, oldest first, each with `kind`, `occurred_at` and `count` (for example offered to 3 agencies): `submitted`, `review_requested`, `approved`, `offered`, `declined`, `accepted`, `paid`, `warranty_until`, `completed`, `refunded`, `commission_due`, `commission_paid` and `closed`. New kinds may be added. Agency names are never shown.

`GET /v1/leads/{id}/earnings` returns `fee`, `creator_guard_amount`, `your_amount` (money or `null`) and `status`: `expected` while a fee is set and the placement has not completed, then `due`, `paid` or `void`; `void` also when the lead is lost, rejected or withdrawn (only a completed placement earns a commission); `null`, with every amount `null`, while no fee is set. Your share is the fee minus the Creator Guard share from [`GET /v1/settings`](https://docs.creator-guard.com/reference/#op-getSettings).
