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.

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
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
// 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
# 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.
  • 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 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: a stale value → 412 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.

Group Fields
Profile age (18–99, below 18 → age_below_18), gender, origin_country, languages (pick-list values), english_level (1–10)
Content content_types (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. 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 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 with error.blockers; a lead that is not a draft answers 409 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 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.