# Leads

A **lead** is one creator submitted by your account. Endpoints (scopes in the [reference](https://docs.creator-guard.com/reference/#tag-leads)):

| Request | Does |
|---|---|
| `POST /v1/leads` | Create a lead, optionally with her listing. |
| `GET /v1/leads` | List your leads, newest first, with filters — see [Pagination](https://docs.creator-guard.com/pagination/). |
| `GET /v1/leads/{id}` | One lead; `?expand=listing,photos,confirmations` adds those objects. |
| `PATCH /v1/leads/{id}` | Change lead fields while she is a draft; `external_id` at any stage. |
| `POST /v1/leads/{id}/withdraw` | Withdraw her while that is allowed. |

`GET /v1/leads/{id}` takes no query parameter but `expand` and [`fields`](https://docs.creator-guard.com/reference/#op-getLead): any other answers [`400 unknown_parameter`](https://docs.creator-guard.com/errors/#unknown_parameter), with the parameter's name in `error.parameter`.

## Create a lead

curl:

```bash
curl -X POST https://api.creator-guard.com/v1/leads \
  -H "Authorization: Bearer $CG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_id": "crm-000042",
    "creator_name": "Mia",
    "instagram_handle": "https://www.instagram.com/miacreates/",
    "other_contact": "Telegram: @mia_tg",
    "platforms": ["OnlyFans", "Instagram", "TikTok"],
    "follower_count": 42000,
    "niche": "Fitness",
    "notes": "Replies fast, wants to start within a month.",
    "consent_confirmed": true,
    "listing": {
      "age": 24,
      "origin_country": "Germany",
      "languages": ["German", "English"],
      "content_types": ["Livestreams", "Custom requests"]
    }
  }'
```

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 = {
  "external_id": "crm-000042",
  "creator_name": "Mia",
  "instagram_handle": "https://www.instagram.com/miacreates/",
  "other_contact": "Telegram: @mia_tg",
  "platforms": ["OnlyFans", "Instagram", "TikTok"],
  "follower_count": 42000,
  "niche": "Fitness",
  "notes": "Replies fast, wants to start within a month.",
  "consent_confirmed": true,
  "listing": {
    "age": 24,
    "origin_country": "Germany",
    "languages": ["German", "English"],
    "content_types": ["Livestreams", "Custom requests"]
  }
};

const res = await fetch('https://api.creator-guard.com/v1/leads', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
  },
  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 = {
    "external_id": "crm-000042",
    "creator_name": "Mia",
    "instagram_handle": "https://www.instagram.com/miacreates/",
    "other_contact": "Telegram: @mia_tg",
    "platforms": ["OnlyFans", "Instagram", "TikTok"],
    "follower_count": 42000,
    "niche": "Fitness",
    "notes": "Replies fast, wants to start within a month.",
    "consent_confirmed": True,
    "listing": {
        "age": 24,
        "origin_country": "Germany",
        "languages": ["German", "English"],
        "content_types": ["Livestreams", "Custom requests"],
    },
}

res = requests.request(
    "POST",
    "https://api.creator-guard.com/v1/leads",
    headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    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)
```

The answer (`201` new, `200` already known) is the lead with `consent`: her consent `status`, her personal consent page `url` and its `expires_at`. The `201` makes her link (valid at least 30 days), so you can send it to her right away. We store links only as hashes, so the `url` is shown only in that `201`: a `200`, `GET /v1/leads/{id}` and an `Idempotency-Key` replay answer `url: null` with the current `expires_at`, and `POST /v1/leads/{id}/consent-link` makes a new link (the old one then only allows a withdrawal). More: [Her confirmations](https://docs.creator-guard.com/listing/#her-confirmations).

## Fields

Only `creator_name` and `consent_confirmed` are required, the same as in the partner portal. Send every other field you know: a contact and her platforms make her much easier to place, and the [listing](https://docs.creator-guard.com/listing/#fields) needs more before she can go on the marketplace.

Strings are trimmed, then checked; lengths count after trimming. `null` for an optional field is the same as leaving it out (on `PATCH` it clears the field; `platforms` takes no `null`, leave it out). Unknown fields are rejected with [`400 unknown_field`](https://docs.creator-guard.com/errors/#unknown_field).

| Field | Type | Rules |
|---|---|---|
| `creator_name` | string | **Required**, 1–120 characters. |
| `instagram_handle` | string | 1–200. `@handle`, `handle` or a profile link (`instagram.com/<handle>`, with or without `www.`, `m.`, `https://`, query or trailing slash). Anything else → [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field). |
| `other_contact` | string | 1–200. Telegram, phone, … |
| `platforms` | string[] | 1–20 entries, each 1–40. |
| `follower_count` | integer | 0–2,147,483,647, on her largest platform. |
| `niche` | string | 1–80. |
| `notes` | string | 1–2,000. For our team only; never shown to agencies. |
| `external_id` | string | 1–100 after trimming, your own reference, unique within your account. See [Idempotency](https://docs.creator-guard.com/idempotency/). |
| `consent_confirmed` | `true` | **Required**, exactly `true` ([`consent_required`](https://docs.creator-guard.com/errors/#consent_required)). See [Data protection](https://docs.creator-guard.com/data-protection/). |
| `listing` | object | Optional: any [listing fields](https://docs.creator-guard.com/listing/#fields), applied as with `PATCH …/listing`; problems are reported as `listing.<field>`. |

Validation reports **every** problem of the body at once in `error.details`.

### Pick-list values

`platforms`, `niche`, `listing.languages` and `listing.content_types` take any text within the limits, but agencies search the portal's pick lists. A value that matches a pick-list value ignoring case and extra spaces is stored in the pick-list spelling (`onlyfans` → `OnlyFans`); repeated values are stored once; anything else is kept as sent. The lists are at [`GET /v1/option-lists`](https://docs.creator-guard.com/reference/#op-getOptionLists) and on [Allowed values](https://docs.creator-guard.com/reference/allowed-values/).

## Duplicates

We recognise a creator we already know by her **normalised Instagram handle** (`@MiaCreates`, `miacreates` and `https://www.instagram.com/miacreates/?hl=en` are the same). `POST /v1/leads` checks your `external_id` first, then the handle. A lead sent without `instagram_handle` gets no handle check: only your `external_id` (or an [`Idempotency-Key`](https://docs.creator-guard.com/idempotency/)) keeps a retry from creating her twice.

| Situation | Answer |
|---|---|
| Your `external_id` is already used by one of your leads | `200` with that lead, **unchanged**. |
| Your own lead with this handle is still a `draft` | `200` with that lead, **updated** with the lead fields you sent (and `listing`, if sent). Its `external_id` and handle spelling stay; change those with `PATCH`. |
| Your own lead with this handle is past `draft` | [`409 duplicate_own_lead`](https://docs.creator-guard.com/errors/#duplicate_own_lead), nothing changes; `error.lead` names her (`id`, `creator_ref`). |
| Another account submitted this handle | [`409 duplicate_other_referrer`](https://docs.creator-guard.com/errors/#duplicate_other_referrer), nothing is saved, nothing about the other account. |
| Nobody has her | `201` with the new lead. |

`duplicate_other_referrer` answers are budgeted: 20 per account in a rolling 24 hours. Once the budget is used up, every request that would check a handle answers [`429 duplicate_limit_reached`](https://docs.creator-guard.com/rate-limits/#duplicate-budget) with `Retry-After`, whether the handle is taken or not. Two requests with the same handle or `external_id` at the same moment create exactly one lead.

## The lead object

Every lead carries `stage`, `next_actions` (what you can do now, and `blockers` that keep her off the marketplace) and a `listing` summary (`status`, `placement_fee`, `photo_count`). Field by field: [Lead](https://docs.creator-guard.com/reference/#schema-Lead). Stages: [Lead lifecycle](https://docs.creator-guard.com/lead-lifecycle/).

## Change a lead

`PATCH /v1/leads/{id}` with only the fields to change:

- Lead fields can change while `next_actions.can_edit_lead` is `true` (stage `draft`); afterwards [`409 lead_locked`](https://docs.creator-guard.com/errors/#lead_locked).
- `external_id` can change at any stage; a value used by another of your leads → [`409 external_id_taken`](https://docs.creator-guard.com/errors/#external_id_taken).
- A new `instagram_handle` goes through the duplicate rules above: held by another account → [`409 duplicate_other_referrer`](https://docs.creator-guard.com/errors/#duplicate_other_referrer) (same budget), held by another of your leads → [`409 duplicate_own_lead`](https://docs.creator-guard.com/errors/#duplicate_own_lead). The lead stays unchanged.
- `instagram_handle` and `other_contact` can both be cleared with `null`, as in the portal: a lead may have no contact. Every other rule for a field you send stays the same.

### Concurrent changes

`POST /v1/leads`, `GET /v1/leads/{id}` and `PATCH /v1/leads/{id}` answer with an `ETag` header, the version of the lead. Send it back unchanged as `If-Match` and the change applies only if nobody changed the lead since you read it:

```http
GET /v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy
→ 200, ETag: "3f2a8c1e5b7d4e2a"

PATCH /v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy
If-Match: "3f2a8c1e5b7d4e2a"
Content-Type: application/json

{"creator_name": "Mia R."}
```

If the lead changed in between — in the portal or by another request — the answer is [`412 precondition_failed`](https://docs.creator-guard.com/errors/#precondition_failed) and nothing changes: read the lead again, apply your change to what you read, and send it with the new `ETag`. Without `If-Match` (or with `If-Match: *`) the last write wins. `If-Match` takes exactly one tag; anything else → [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field).

The lead's `ETag` covers the lead fields. Her listing has its own: use the `ETag` of `GET /v1/leads/{id}/listing` for `PATCH …/listing` (see [Listing & review](https://docs.creator-guard.com/listing/#change-the-listing)).

## Withdraw a lead

`POST /v1/leads/{id}/withdraw` while `next_actions.can_withdraw` (`draft` or `in_review`, and no agency offer under way); otherwise [`409 invalid_state`](https://docs.creator-guard.com/errors/#invalid_state) with `error.current_state`. Withdrawing is final.

## Other accounts' leads

A lead id of another account answers [`404 not_found`](https://docs.creator-guard.com/errors/#not_found), exactly like an id that does not exist.
