Leads
A lead is one creator submitted by your account. Endpoints (scopes in the reference):
| Request | Does |
|---|---|
POST /v1/leads |
Create a lead, optionally with her listing. |
GET /v1/leads |
List your leads, newest first, with filters — see 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: any other answers 400 unknown_parameter, with the parameter's name in error.parameter.
Create a lead
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"]
}
}'// 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);# 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.
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 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.
| 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. |
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. |
consent_confirmed |
true |
Required, exactly true (consent_required). See Data protection. |
listing |
object | Optional: any 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 and on 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) 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, nothing changes; error.lead names her (id, creator_ref). |
| Another account submitted this handle | 409 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 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. Stages: Lead lifecycle.
Change a lead
PATCH /v1/leads/{id} with only the fields to change:
- Lead fields can change while
next_actions.can_edit_leadistrue(stagedraft); afterwards409 lead_locked. external_idcan change at any stage; a value used by another of your leads →409 external_id_taken.- A new
instagram_handlegoes through the duplicate rules above: held by another account →409 duplicate_other_referrer(same budget), held by another of your leads →409 duplicate_own_lead. The lead stays unchanged. instagram_handleandother_contactcan both be cleared withnull, 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:
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 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.
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).
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 with error.current_state. Withdrawing is final.
Other accounts' leads
A lead id of another account answers 404 not_found, exactly like an id that does not exist.