Beta — the platform and this API are in beta. The rules on this page are binding; we may add features and tighten validation without notice.

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.

curl
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"
JavaScript
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'}`);
Python
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:

curl
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"
JavaScript
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}`);
Python
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.

curl
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"
JavaScript
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);
Python
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).

curl
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"
JavaScript
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(', '));
Python
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.

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):

curl
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")"
JavaScript
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);
Python
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.

curl
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")"
fi
JavaScript
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-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(', ')}`);
Python
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_changed and the other lead events with a webhook.
  • Pull: list what changed since your last sync with updated_since — Pagination & sync.
curl
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)"
JavaScript
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)`);
Python
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.

curl
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"
JavaScript
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);
Python
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.

JavaScript
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);
Python
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.