Referral partner guide
This guide walks one creator through a complete integration, from your first request to your commission. Every step has a runnable sample in curl, JavaScript and Python; the pages it links to have every field and rule. Agencies refer creators with the same endpoints.
Build it with a cg_test_ key first: the sandbox has helpers that play the creator and our review, so you can run the whole path in minutes.
1. Check your key and your terms
GET /v1/me names your account and shows in terms whether your terms are accepted. Reads always work; every write needs the current referrer_terms (otherwise 403 terms_not_accepted), and an account that is pending or disabled gets 403 account_not_active.
BASE="${CG_API_BASE:-https://api.creator-guard.com}"
auth() { printf 'Authorization: Bearer %s\n' "$CG_API_KEY"; } # read through a file descriptor: the key never shows in `ps`
api() { # api METHOD PATH [JSON] [HEADER] → body on stdout; HTTP >= 400 → status + body on stderr, return 1
local out
out="$(curl -sS -X "$1" -H @<(auth) -H "Content-Type: application/json" ${4:+-H "$4"} ${3:+--data "$3"} \
-w "\n%{http_code}" "$BASE$2")"
[[ "${out##*$'\n'}" -lt 400 ]] || { echo "${out##*$'\n'} ${out%$'\n'*}" >&2; return 1; }
printf "%s\n" "${out%$'\n'*}"
}
me="$(api GET /v1/me)"
jq -r '"\(.type) account \(.id) is \(.status)", (.terms[] | "\(.type): accepted \(.accepted)")' <<<"$me"const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com';
const res = await fetch(`${BASE}/v1/me`, { headers: { Authorization: `Bearer ${process.env.CG_API_KEY}` } });
const me = await res.json();
if (!res.ok) throw new Error(`${res.status} ${me.error.code}: ${me.error.message}`);
console.log(`${me.type} account ${me.id} is ${me.status}`);
for (const t of me.terms) console.log(`${t.type}: ${t.accepted ? `accepted v${t.accepted_version}` : 'not accepted'}`);import json
import os
import urllib.error
import urllib.request
BASE = os.environ.get("CG_API_BASE", "https://api.creator-guard.com")
def call(method, path, body=None, headers=None):
"""(status, headers, JSON body); 4xx/5xx are returned, not raised: they carry error.code."""
req = urllib.request.Request(BASE + path, method=method, data=None if body is None else json.dumps(body).encode(),
headers={"Authorization": "Bearer " + os.environ["CG_API_KEY"],
"Content-Type": "application/json", **(headers or {})})
try:
with urllib.request.urlopen(req, timeout=30) as res:
return res.status, res.headers, json.load(res)
except urllib.error.HTTPError as err:
return err.code, err.headers, json.load(err)
def fail(status, data):
raise SystemExit(f"{status} {data['error']['code']}: {data['error']['message']}")
status, _, me = call("GET", "/v1/me")
if status != 200:
fail(status, me)
print(f"{me['type']} account {me['id']} is {me['status']}")
for t in me["terms"]:
print(t["type"], f"accepted v{t['accepted_version']}" if t["accepted"] else "not accepted")Accept the terms once — in the portal, or with the current version from GET /v1/agreements:
BASE="${CG_API_BASE:-https://api.creator-guard.com}"
auth() { printf 'Authorization: Bearer %s\n' "$CG_API_KEY"; } # read through a file descriptor: the key never shows in `ps`
api() { # api METHOD PATH [JSON] [HEADER] → body on stdout; HTTP >= 400 → status + body on stderr, return 1
local out
out="$(curl -sS -X "$1" -H @<(auth) -H "Content-Type: application/json" ${4:+-H "$4"} ${3:+--data "$3"} \
-w "\n%{http_code}" "$BASE$2")"
[[ "${out##*$'\n'}" -lt 400 ]] || { echo "${out##*$'\n'} ${out%$'\n'*}" >&2; return 1; }
printf "%s\n" "${out%$'\n'*}"
}
type="$(api GET /v1/me | jq -r 'if .type == "agency" then "agency_terms" else "referrer_terms" end')"
version="$(api GET /v1/agreements | jq --arg t "$type" '.data[] | select(.type == $t) | .current_version')"
# Show the text first: GET /v1/agreements/$type/$version returns it as Markdown (body_md).
accepted="$(api POST "/v1/agreements/$type/accept" "{\"version\": $version}" "Idempotency-Key: $(uuidgen)")"
jq -r '"\(.type) v\(.accepted_version) accepted at \(.accepted_at)"' <<<"$accepted"const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com';
const headers = { Authorization: `Bearer ${process.env.CG_API_KEY}`, 'Content-Type': 'application/json' };
async function call(method, path, body) {
const res = await fetch(`${BASE}${path}`, { method, body: body && JSON.stringify(body),
headers: method === 'POST' ? { ...headers, 'Idempotency-Key': crypto.randomUUID() } : headers });
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
return data;
}
const me = await call('GET', '/v1/me');
const type = me.type === 'agency' ? 'agency_terms' : 'referrer_terms';
const terms = (await call('GET', '/v1/agreements')).data.find((a) => a.type === type);
// Show the text to the person who accepts: GET /v1/agreements/{type}/{version} returns it as Markdown.
const accepted = await call('POST', `/v1/agreements/${type}/accept`, { version: terms.current_version });
console.log(`${type} v${accepted.accepted_version} accepted at ${accepted.accepted_at}`);import json
import os
import urllib.error
import urllib.request
import uuid
BASE = os.environ.get("CG_API_BASE", "https://api.creator-guard.com")
def call(method, path, body=None, headers=None):
"""(status, headers, JSON body); 4xx/5xx are returned, not raised: they carry error.code."""
req = urllib.request.Request(BASE + path, method=method, data=None if body is None else json.dumps(body).encode(),
headers={"Authorization": "Bearer " + os.environ["CG_API_KEY"],
"Content-Type": "application/json", **(headers or {})})
try:
with urllib.request.urlopen(req, timeout=30) as res:
return res.status, res.headers, json.load(res)
except urllib.error.HTTPError as err:
return err.code, err.headers, json.load(err)
def fail(status, data):
raise SystemExit(f"{status} {data['error']['code']}: {data['error']['message']}")
status, _, me = call("GET", "/v1/me")
if status != 200:
fail(status, me)
kind = "agency_terms" if me["type"] == "agency" else "referrer_terms"
status, _, agreements = call("GET", "/v1/agreements")
if status != 200:
fail(status, agreements)
terms = next(a for a in agreements["data"] if a["type"] == kind)
# Show the text to the person who accepts: GET /v1/agreements/{type}/{version} returns it as Markdown.
status, _, accepted = call("POST", f"/v1/agreements/{kind}/accept", {"version": terms["current_version"]},
{"Idempotency-Key": str(uuid.uuid4())})
if status != 200:
fail(status, accepted)
print(f"{kind} v{accepted['accepted_version']} accepted at {accepted['accepted_at']}")What each scope allows: Authentication. Uploading photos needs a key with photos:write.
2. Create the lead
POST /v1/leads with her name and consent_confirmed: true — your statement that she agreed to be submitted — plus everything else you know: a contact (instagram_handle or other_contact), platforms, followers. Send your own external_id and an Idempotency-Key, so a retry after a timeout can never create her twice.
BASE="${CG_API_BASE:-https://api.creator-guard.com}"
auth() { printf 'Authorization: Bearer %s\n' "$CG_API_KEY"; } # read through a file descriptor: the key never shows in `ps`
api() { # api METHOD PATH [JSON] [HEADER] → body on stdout; HTTP >= 400 → status + body on stderr, return 1
local out
out="$(curl -sS -X "$1" -H @<(auth) -H "Content-Type: application/json" ${4:+-H "$4"} ${3:+--data "$3"} \
-w "\n%{http_code}" "$BASE$2")"
[[ "${out##*$'\n'}" -lt 400 ]] || { echo "${out##*$'\n'} ${out%$'\n'*}" >&2; return 1; }
printf "%s\n" "${out%$'\n'*}"
}
# external_id = your own id: repeating it returns the existing lead (200) instead of a second one.
lead='{"external_id": "docs-sample-create-lead", "creator_name": "Docs Sample",
"other_contact": "Telegram: @docs_sample", "platforms": ["OnlyFans", "Instagram"], "consent_confirmed": true}'
key="$(uuidgen)" # keep it until you have an answer; a retry with the same key never creates a second lead
data="$(api POST /v1/leads "$lead" "Idempotency-Key: $key" || api POST /v1/leads "$lead" "Idempotency-Key: $key")"
jq -r '"\(.id) \(.creator_ref) \(.stage)"' <<<"$data"const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com';
const lead = {
external_id: 'docs-sample-create-lead', // your own id: repeating it returns the existing lead (200)
creator_name: 'Docs Sample',
other_contact: 'Telegram: @docs_sample',
platforms: ['OnlyFans', 'Instagram'],
consent_confirmed: true,
};
// One key per lead, kept until you have an answer: a retry with the same key never creates a second lead.
const idempotencyKey = crypto.randomUUID();
async function createLead() {
return fetch(`${BASE}/v1/leads`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.CG_API_KEY}`, 'Content-Type': 'application/json',
'Idempotency-Key': idempotencyKey },
body: JSON.stringify(lead),
});
}
let res;
try { res = await createLead(); } catch { res = await createLead(); } // network error: same key, same body
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status === 201 ? 'created' : 'already known', data.id, data.creator_ref, data.stage);import json
import os
import urllib.error
import urllib.request
import uuid
BASE = os.environ.get("CG_API_BASE", "https://api.creator-guard.com")
def call(method, path, body=None, headers=None):
"""(status, headers, JSON body); 4xx/5xx are returned, not raised: they carry error.code."""
req = urllib.request.Request(BASE + path, method=method, data=None if body is None else json.dumps(body).encode(),
headers={"Authorization": "Bearer " + os.environ["CG_API_KEY"],
"Content-Type": "application/json", **(headers or {})})
try:
with urllib.request.urlopen(req, timeout=30) as res:
return res.status, res.headers, json.load(res)
except urllib.error.HTTPError as err:
return err.code, err.headers, json.load(err)
def fail(status, data):
raise SystemExit(f"{status} {data['error']['code']}: {data['error']['message']}")
lead = {
"external_id": "docs-sample-create-lead", # your own id: repeating it returns the existing lead (200)
"creator_name": "Docs Sample",
"other_contact": "Telegram: @docs_sample",
"platforms": ["OnlyFans", "Instagram"],
"consent_confirmed": True,
}
# One key per lead, kept until you have an answer: a retry with the same key never creates a second lead.
key = str(uuid.uuid4())
try:
status, _, data = call("POST", "/v1/leads", lead, {"Idempotency-Key": key})
except urllib.error.URLError: # network error: same key, same body
status, _, data = call("POST", "/v1/leads", lead, {"Idempotency-Key": key})
if status not in (200, 201):
fail(status, data)
print("created" if status == 201 else "already known", data["id"], data["creator_ref"], data["stage"])201 is a new lead, 200 one we already had: your external_id was used before, or your own lead with that Instagram handle is still a draft. A handle another account submitted answers 409 duplicate_other_referrer. All cases: Duplicates and Idempotency & retries.
3. Complete her listing
Every lead carries next_actions: what you may do now and the blockers that still keep her off the marketplace. Use them instead of rebuilding the rules. Fill the listing with PATCH /v1/leads/{id}/listing, sending only what changes; send the ETag you read as If-Match, so you never overwrite a change made in the portal in the meantime (412 precondition_failed — read again and retry).
BASE="${CG_API_BASE:-https://api.creator-guard.com}"
auth() { printf 'Authorization: Bearer %s\n' "$CG_API_KEY"; } # read through a file descriptor: the key never shows in `ps`
api() { # api METHOD PATH [JSON] [HEADER] → body on stdout; HTTP >= 400 → status + body on stderr, return 1
local out
out="$(curl -sS -X "$1" -H @<(auth) -H "Content-Type: application/json" ${4:+-H "$4"} ${3:+--data "$3"} \
-w "\n%{http_code}" "$BASE$2")"
[[ "${out##*$'\n'}" -lt 400 ]] || { echo "${out##*$'\n'} ${out%$'\n'*}" >&2; return 1; }
printf "%s\n" "${out%$'\n'*}"
}
lead='{"external_id": "docs-sample-update-listing", "creator_name": "Docs Sample",
"other_contact": "Telegram: @docs_sample", "platforms": ["OnlyFans"], "consent_confirmed": true}'
id="$(api POST /v1/leads "$lead" "Idempotency-Key: $(uuidgen)" | jq -r .id)"
# If-Match = the ETag you read: a change by someone else in between gives 412 instead of being overwritten.
etag="$(curl -sS --fail-with-body -o /dev/null -D - -H @<(auth) "$BASE/v1/leads/$id/listing" |
tr -d '\r' | sed -n 's/^[Ee][Tt][Aa][Gg]: //p')"
listing="$(api PATCH "/v1/leads/$id/listing" '{"age": 24, "origin_country": "Germany", "languages": ["German", "English"]}' \
"If-Match: $etag")" # 412 → read the listing again and repeat
jq -r '"listing \(.status), age \(.age), languages \(.languages | join(", "))"' <<<"$listing"const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com';
const headers = { Authorization: `Bearer ${process.env.CG_API_KEY}`, 'Content-Type': 'application/json' };
async function call(method, path, body, extra = {}) {
const res = await fetch(`${BASE}${path}`, { method, headers: { ...headers, ...extra }, body: body && JSON.stringify(body) });
const data = await res.json();
if (!res.ok && res.status !== 412) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
return { res, data };
}
const lead = (await call('POST', '/v1/leads', { external_id: 'docs-sample-update-listing', creator_name: 'Docs Sample',
other_contact: 'Telegram: @docs_sample', platforms: ['OnlyFans'], consent_confirmed: true },
{ 'Idempotency-Key': crypto.randomUUID() })).data;
const path = `/v1/leads/${lead.id}/listing`;
const change = { age: 24, origin_country: 'Germany', languages: ['German', 'English'] };
let patched;
for (let attempt = 1; attempt <= 3; attempt++) {
const read = await call('GET', path);
// If-Match = the ETag you read: a change by someone else in between gives 412 instead of being overwritten.
patched = await call('PATCH', path, change, { 'If-Match': read.res.headers.get('etag') });
if (patched.res.status !== 412) break;
}
if (!patched.res.ok) throw new Error('the listing kept changing; try again later');
console.log('listing', patched.data.status, 'age', patched.data.age, 'languages', patched.data.languages.join(', '));import json
import os
import urllib.error
import urllib.request
import uuid
BASE = os.environ.get("CG_API_BASE", "https://api.creator-guard.com")
def call(method, path, body=None, headers=None):
"""(status, headers, JSON body); 4xx/5xx are returned, not raised: they carry error.code."""
req = urllib.request.Request(BASE + path, method=method, data=None if body is None else json.dumps(body).encode(),
headers={"Authorization": "Bearer " + os.environ["CG_API_KEY"],
"Content-Type": "application/json", **(headers or {})})
try:
with urllib.request.urlopen(req, timeout=30) as res:
return res.status, res.headers, json.load(res)
except urllib.error.HTTPError as err:
return err.code, err.headers, json.load(err)
def fail(status, data):
raise SystemExit(f"{status} {data['error']['code']}: {data['error']['message']}")
LEAD = {"external_id": "docs-sample-update-listing", "creator_name": "Docs Sample",
"other_contact": "Telegram: @docs_sample", "platforms": ["OnlyFans"], "consent_confirmed": True}
status, _, lead = call("POST", "/v1/leads", LEAD, {"Idempotency-Key": str(uuid.uuid4())})
if status not in (200, 201):
fail(status, lead)
path = f"/v1/leads/{lead['id']}/listing"
change = {"age": 24, "origin_country": "Germany", "languages": ["German", "English"]}
for attempt in range(3):
status, headers, listing = call("GET", path)
if status != 200:
fail(status, listing)
# If-Match = the ETag you read: a change by someone else in between gives 412 instead of being overwritten.
status, _, listing = call("PATCH", path, change, {"If-Match": headers["ETag"]})
if status != 412:
break
if status != 200:
fail(status, listing)
print("listing", listing["status"], "age", listing["age"], "languages", ", ".join(listing["languages"]))Upload three photos with POST /v1/leads/{id}/photos (multipart, field file): see Photos. Every field and the fee: Listing & review.
4. Her consent and 18+ confirmation
Only the creator herself confirms that she is 18 or older and consents to be introduced to agencies. Send her the personal link — it also comes with the new lead as consent.url (only in that 201; links are stored hashed, a new call makes a new link; the old one then only allows a withdrawal):
BASE="${CG_API_BASE:-https://api.creator-guard.com}"
auth() { printf 'Authorization: Bearer %s\n' "$CG_API_KEY"; } # read through a file descriptor: the key never shows in `ps`
api() { # api METHOD PATH [JSON] [HEADER] → body on stdout; HTTP >= 400 → status + body on stderr, return 1
local out
out="$(curl -sS -X "$1" -H @<(auth) -H "Content-Type: application/json" ${4:+-H "$4"} ${3:+--data "$3"} \
-w "\n%{http_code}" "$BASE$2")"
[[ "${out##*$'\n'}" -lt 400 ]] || { echo "${out##*$'\n'} ${out%$'\n'*}" >&2; return 1; }
printf "%s\n" "${out%$'\n'*}"
}
lead='{"external_id": "docs-sample-consent-link", "creator_name": "Docs Sample",
"other_contact": "Telegram: @docs_sample", "platforms": ["OnlyFans"], "consent_confirmed": true}'
id="$(api POST /v1/leads "$lead" "Idempotency-Key: $(uuidgen)" | jq -r .id)"
link="$(api POST "/v1/leads/$id/consent-link" "" "Idempotency-Key: $(uuidgen)")"
# Send .url to her (it is personal: do not log it). She confirms consent and 18+ herself.
echo "consent link valid until $(jq -r .expires_at <<<"$link")"const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com';
const headers = { Authorization: `Bearer ${process.env.CG_API_KEY}`, 'Content-Type': 'application/json' };
const post = (path, body) => fetch(`${BASE}${path}`, { method: 'POST', body: body && JSON.stringify(body),
headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() } });
const created = await post('/v1/leads', { external_id: 'docs-sample-consent-link', creator_name: 'Docs Sample',
other_contact: 'Telegram: @docs_sample', platforms: ['OnlyFans'], consent_confirmed: true });
const lead = await created.json();
if (!created.ok) throw new Error(`${created.status} ${lead.error.code}: ${lead.error.message}`);
const res = await post(`/v1/leads/${lead.id}/consent-link`);
const link = await res.json();
if (!res.ok) throw new Error(`${res.status} ${link.error.code}: ${link.error.message}`);
// Send link.url to her (it is personal: do not log it). She confirms consent and 18+ herself.
console.log('consent link valid until', link.expires_at);import json
import os
import urllib.error
import urllib.request
import uuid
BASE = os.environ.get("CG_API_BASE", "https://api.creator-guard.com")
def call(method, path, body=None, headers=None):
"""(status, headers, JSON body); 4xx/5xx are returned, not raised: they carry error.code."""
req = urllib.request.Request(BASE + path, method=method, data=None if body is None else json.dumps(body).encode(),
headers={"Authorization": "Bearer " + os.environ["CG_API_KEY"],
"Content-Type": "application/json", **(headers or {})})
try:
with urllib.request.urlopen(req, timeout=30) as res:
return res.status, res.headers, json.load(res)
except urllib.error.HTTPError as err:
return err.code, err.headers, json.load(err)
def fail(status, data):
raise SystemExit(f"{status} {data['error']['code']}: {data['error']['message']}")
LEAD = {"external_id": "docs-sample-consent-link", "creator_name": "Docs Sample",
"other_contact": "Telegram: @docs_sample", "platforms": ["OnlyFans"], "consent_confirmed": True}
status, _, lead = call("POST", "/v1/leads", LEAD, {"Idempotency-Key": str(uuid.uuid4())})
if status not in (200, 201):
fail(status, lead)
status, _, link = call("POST", f"/v1/leads/{lead['id']}/consent-link", None, {"Idempotency-Key": str(uuid.uuid4())})
if status != 200:
fail(status, link)
# Send link["url"] to her (it is personal: do not log it). She confirms consent and 18+ herself.
print("consent link valid until", link["expires_at"])Never open the link and confirm on her behalf. GET /v1/leads/{id}/confirmations shows where she stands. In the sandbox, POST /v1/test-helpers/leads/{id}/confirm plays her part.
5. Submit for review
When next_actions.can_submit_for_review is true, submit her. With blockers left the answer is 422 not_ready_for_review with the list in error.blockers. Submitting ends the draft: the lead fields lock (external_id stays changeable); listing fields and the fee can change until she goes live.
BASE="${CG_API_BASE:-https://api.creator-guard.com}"
auth() { printf 'Authorization: Bearer %s\n' "$CG_API_KEY"; } # read through a file descriptor: the key never shows in `ps`
api() { # api METHOD PATH [JSON] [HEADER] → body on stdout; HTTP >= 400 → status + body on stderr, return 1
local out
out="$(curl -sS -X "$1" -H @<(auth) -H "Content-Type: application/json" ${4:+-H "$4"} ${3:+--data "$3"} \
-w "\n%{http_code}" "$BASE$2")"
[[ "${out##*$'\n'}" -lt 400 ]] || { echo "${out##*$'\n'} ${out%$'\n'*}" >&2; return 1; }
printf "%s\n" "${out%$'\n'*}"
}
lead='{"external_id": "docs-sample-submit-for-review", "creator_name": "Docs Sample",
"other_contact": "Telegram: @docs_sample", "platforms": ["OnlyFans"], "consent_confirmed": true}'
id="$(api POST /v1/leads "$lead" "Idempotency-Key: $(uuidgen)" | jq -r .id)"
errors="$(mktemp)" && trap 'rm -f "$errors"' EXIT
if result="$(api POST "/v1/leads/$id/submit-for-review" "" "Idempotency-Key: $(uuidgen)" 2>"$errors")"; then
echo "in review: $(jq -r .stage <<<"$result")"
else # 422 not_ready_for_review is not an outage: show what is missing (photos_missing, consent_missing, …)
read -r status error < "$errors"
[[ "$status" == 422 && "$(jq -r .error.code <<<"$error")" == not_ready_for_review ]] || { echo "$status $error" >&2; exit 1; }
echo "not ready: $(jq -r '.error.blockers | join(", ")' <<<"$error")"
ficonst BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com';
const headers = { Authorization: `Bearer ${process.env.CG_API_KEY}`, 'Content-Type': 'application/json' };
const post = (path, body) => fetch(`${BASE}${path}`, { method: 'POST', body: body && JSON.stringify(body),
headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() } });
const created = await post('/v1/leads', { external_id: 'docs-sample-submit-for-review', creator_name: 'Docs Sample',
other_contact: 'Telegram: @docs_sample', platforms: ['OnlyFans'], consent_confirmed: true });
const lead = await created.json();
if (!created.ok) throw new Error(`${created.status} ${lead.error.code}: ${lead.error.message}`);
const res = await post(`/v1/leads/${lead.id}/submit-for-review`);
const data = await res.json();
let result;
if (res.ok) {
result = { submitted: true, stage: data.stage };
} else if (res.status === 422 && data.error.code === 'not_ready_for_review') {
// Not an outage: tell the user what is missing, e.g. photos_missing, consent_missing.
result = { submitted: false, blockers: data.error.blockers };
} else {
throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
}
console.log(result.submitted ? `in review (${result.stage})` : `not ready: ${result.blockers.join(', ')}`);import json
import os
import urllib.error
import urllib.request
import uuid
BASE = os.environ.get("CG_API_BASE", "https://api.creator-guard.com")
def call(method, path, body=None, headers=None):
"""(status, headers, JSON body); 4xx/5xx are returned, not raised: they carry error.code."""
req = urllib.request.Request(BASE + path, method=method, data=None if body is None else json.dumps(body).encode(),
headers={"Authorization": "Bearer " + os.environ["CG_API_KEY"],
"Content-Type": "application/json", **(headers or {})})
try:
with urllib.request.urlopen(req, timeout=30) as res:
return res.status, res.headers, json.load(res)
except urllib.error.HTTPError as err:
return err.code, err.headers, json.load(err)
def fail(status, data):
raise SystemExit(f"{status} {data['error']['code']}: {data['error']['message']}")
LEAD = {"external_id": "docs-sample-submit-for-review", "creator_name": "Docs Sample",
"other_contact": "Telegram: @docs_sample", "platforms": ["OnlyFans"], "consent_confirmed": True}
status, _, lead = call("POST", "/v1/leads", LEAD, {"Idempotency-Key": str(uuid.uuid4())})
if status not in (200, 201):
fail(status, lead)
status, _, data = call("POST", f"/v1/leads/{lead['id']}/submit-for-review", None, {"Idempotency-Key": str(uuid.uuid4())})
if status == 200:
result = {"submitted": True, "stage": data["stage"]}
elif status == 422 and data["error"]["code"] == "not_ready_for_review":
# Not an outage: tell the user what is missing, e.g. photos_missing, consent_missing.
result = {"submitted": False, "blockers": data["error"]["blockers"]}
else:
fail(status, data)
print(f"in review ({result['stage']})" if result["submitted"] else "not ready: " + ", ".join(result["blockers"]))6. Follow her stages
stage moves from draft through review and the agency placement to placed, or ends as rejected, lost or withdrawn — see Lead lifecycle. You see milestones, never agency names.
- Push: subscribe to
lead.stage_changedand the other lead events with a webhook. - Pull: list what changed since your last sync with
updated_since— Pagination & sync.
BASE="${CG_API_BASE:-https://api.creator-guard.com}"
auth() { printf 'Authorization: Bearer %s\n' "$CG_API_KEY"; } # read through a file descriptor: the key never shows in `ps`
api() { # api METHOD PATH [JSON] [HEADER] → body on stdout; HTTP >= 400 → status + body on stderr, return 1
local out
out="$(curl -sS -X "$1" -H @<(auth) -H "Content-Type: application/json" ${4:+-H "$4"} ${3:+--data "$3"} \
-w "\n%{http_code}" "$BASE$2")"
[[ "${out##*$'\n'}" -lt 400 ]] || { echo "${out##*$'\n'} ${out%$'\n'*}" >&2; return 1; }
printf "%s\n" "${out%$'\n'*}"
}
cursor="" count=0 pages=0
while :; do
page="$(api GET "/v1/leads?limit=100${cursor:+&starting_after=$cursor}")"
count=$((count + $(jq '.data | length' <<<"$page"))) pages=$((pages + 1))
[[ "$(jq -r .has_more <<<"$page")" == true ]] || break
cursor="$(jq -r .next_cursor <<<"$page")"
done
echo "$count leads in $pages page(s)"const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com';
const leads = [];
let cursor = null;
let pages = 0;
do {
const url = new URL(`${BASE}/v1/leads`);
url.searchParams.set('limit', '100');
if (cursor) url.searchParams.set('starting_after', cursor);
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.CG_API_KEY}` } });
const page = await res.json();
if (!res.ok) throw new Error(`${res.status} ${page.error.code}: ${page.error.message}`);
leads.push(...page.data);
cursor = page.has_more ? page.next_cursor : null;
pages += 1;
} while (cursor);
console.log(`${leads.length} leads in ${pages} page(s)`);import json
import os
import urllib.error
import urllib.request
BASE = os.environ.get("CG_API_BASE", "https://api.creator-guard.com")
def call(method, path, body=None, headers=None):
"""(status, headers, JSON body); 4xx/5xx are returned, not raised: they carry error.code."""
req = urllib.request.Request(BASE + path, method=method, data=None if body is None else json.dumps(body).encode(),
headers={"Authorization": "Bearer " + os.environ["CG_API_KEY"],
"Content-Type": "application/json", **(headers or {})})
try:
with urllib.request.urlopen(req, timeout=30) as res:
return res.status, res.headers, json.load(res)
except urllib.error.HTTPError as err:
return err.code, err.headers, json.load(err)
def fail(status, data):
raise SystemExit(f"{status} {data['error']['code']}: {data['error']['message']}")
leads, cursor, pages = [], None, 0
while True:
query = "?limit=100" + (f"&starting_after={cursor}" if cursor else "")
status, _, page = call("GET", "/v1/leads" + query)
if status != 200:
fail(status, page)
leads += page["data"]
pages += 1
if not page["has_more"]:
break
cursor = page["next_cursor"]
print(f"{len(leads)} leads in {pages} page(s)")GET /v1/leads/{id} returns one lead; ?expand=listing,photos,confirmations adds those objects. GET /v1/leads/{id}/timeline lists her milestones.
BASE="${CG_API_BASE:-https://api.creator-guard.com}"
auth() { printf 'Authorization: Bearer %s\n' "$CG_API_KEY"; } # read through a file descriptor: the key never shows in `ps`
api() { # api METHOD PATH [JSON] [HEADER] → body on stdout; HTTP >= 400 → status + body on stderr, return 1
local out
out="$(curl -sS -X "$1" -H @<(auth) -H "Content-Type: application/json" ${4:+-H "$4"} ${3:+--data "$3"} \
-w "\n%{http_code}" "$BASE$2")"
[[ "${out##*$'\n'}" -lt 400 ]] || { echo "${out##*$'\n'} ${out%$'\n'*}" >&2; return 1; }
printf "%s\n" "${out%$'\n'*}"
}
id="$(api GET "/v1/leads?limit=1" | jq -r '.data[0].id // empty')"
[[ -n "$id" ]] || { echo "no lead yet: create one first" >&2; exit 1; }
lead="$(api GET "/v1/leads/$id?expand=listing,confirmations")"
jq -r '"\(.creator_ref) \(.stage) blockers: \(.next_actions.blockers | join(", "))",
"consent: \(.confirmations.consent.status), 18+: \(.confirmations.age_confirmation.status)"' <<<"$lead"const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com';
const headers = { Authorization: `Bearer ${process.env.CG_API_KEY}` };
async function get(path) {
const res = await fetch(`${BASE}${path}`, { headers });
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
return data;
}
const [newest] = (await get('/v1/leads?limit=1')).data;
if (!newest) throw new Error('no lead yet: create one first');
const lead = await get(`/v1/leads/${newest.id}?expand=listing,confirmations`);
console.log(lead.creator_ref, lead.stage, 'blockers:', lead.next_actions.blockers.join(', ') || 'none');
console.log('consent:', lead.confirmations.consent.status, '18+:', lead.confirmations.age_confirmation.status);import json
import os
import urllib.error
import urllib.request
BASE = os.environ.get("CG_API_BASE", "https://api.creator-guard.com")
def call(method, path, body=None, headers=None):
"""(status, headers, JSON body); 4xx/5xx are returned, not raised: they carry error.code."""
req = urllib.request.Request(BASE + path, method=method, data=None if body is None else json.dumps(body).encode(),
headers={"Authorization": "Bearer " + os.environ["CG_API_KEY"],
"Content-Type": "application/json", **(headers or {})})
try:
with urllib.request.urlopen(req, timeout=30) as res:
return res.status, res.headers, json.load(res)
except urllib.error.HTTPError as err:
return err.code, err.headers, json.load(err)
def fail(status, data):
raise SystemExit(f"{status} {data['error']['code']}: {data['error']['message']}")
status, _, page = call("GET", "/v1/leads?limit=1")
if status != 200:
fail(status, page)
if not page["data"]:
raise SystemExit("no lead yet: create one first")
status, _, lead = call("GET", f"/v1/leads/{page['data'][0]['id']}?expand=listing,confirmations")
if status != 200:
fail(status, lead)
print(lead["creator_ref"], lead["stage"], "blockers:", ", ".join(lead["next_actions"]["blockers"]) or "none")
print("consent:", lead["confirmations"]["consent"]["status"], "18+:", lead["confirmations"]["age_confirmation"]["status"])7. Earnings
GET /v1/leads/{id}/earnings shows the fee and your amount for one creator; GET /v1/commissions lists your booked commissions, with the commission.created, commission.paid and commission.voided events. Payout details are changed only in the portal. Details: Account & earnings.
Errors and retries
Every error has the same body: branch on error.code, show error.message to people, and quote error.request_id when you contact us. Wait out 429 for Retry-After seconds and retry 5xx with the same Idempotency-Key; never resend another 4xx unchanged.
const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com';
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function request(method, path, attempts = 4) {
for (let attempt = 1; ; attempt++) {
const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${process.env.CG_API_KEY}` } });
const data = await res.json();
if (res.ok) return { ok: true, data };
const retryable = res.status === 429 || res.status >= 500;
if (!retryable || attempt === attempts) return { ok: false, status: res.status, error: data.error };
// 429: wait exactly Retry-After seconds; 5xx: back off. Quote error.request_id when you contact support.
const seconds = Number(res.headers.get('retry-after')) || 2 ** attempt;
await sleep(Math.min(seconds, 60) * 1000);
}
}
const result = await request('GET', `/v1/leads/lead_${'a'.repeat(26)}`);
let outcome;
if (result.ok) outcome = 'found';
else if (result.error.code === 'not_found') outcome = 'not_found'; // unknown id, or not one of your leads
else if (result.error.code === 'insufficient_scope') outcome = `key lacks ${result.error.scope}`;
else throw new Error(`${result.status} ${result.error.code} (request ${result.error.request_id})`);
console.log('outcome:', outcome);import json
import os
import time
import urllib.error
import urllib.request
BASE = os.environ.get("CG_API_BASE", "https://api.creator-guard.com")
def request(method, path, attempts=4):
"""(True, data) on success, (False, status, error) after the last attempt; retries 429 and 5xx only."""
for attempt in range(1, attempts + 1):
req = urllib.request.Request(BASE + path, method=method,
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"})
try:
with urllib.request.urlopen(req, timeout=30) as res:
return True, json.load(res)
except urllib.error.HTTPError as err:
error = json.load(err)["error"]
if not (err.code == 429 or err.code >= 500) or attempt == attempts:
return False, err.code, error
# 429: wait exactly Retry-After seconds; 5xx: back off. Quote error["request_id"] to support.
time.sleep(min(int(err.headers.get("Retry-After") or 2 ** attempt), 60))
result = request("GET", "/v1/leads/lead_" + "a" * 26)
if result[0]:
outcome = "found"
elif result[2]["code"] == "not_found":
outcome = "not_found" # unknown id, or not one of your leads
elif result[2]["code"] == "insufficient_scope":
outcome = f"key lacks {result[2]['scope']}"
else:
raise SystemExit(f"{result[1]} {result[2]['code']} (request {result[2]['request_id']})")
print("outcome:", outcome)The SDKs do all of this for you. All codes: Errors. Limits: Rate limits.