# Creator Guard Platform API — complete documentation > Every page of https://docs.creator-guard.com in sidebar order, as Markdown, with the API reference rendered from https://docs.creator-guard.com/openapi.yaml (OpenAPI 3.1.0, version 1.23.0). Index: https://docs.creator-guard.com/llms.txt. Find your way by headings: `#` starts a page (followed by its Source URL), the API reference lists every operation as `#### ` followed by `` `METHOD /path` · operationId `…` ``, every schema as a `####` heading with its name in backticks. Code samples show JavaScript only; each page's Markdown twin has curl and Python too. --- # Creator Guard Platform API Source: https://docs.creator-guard.com/ Everything the partner portal does with a creator, from your own system: submit her, complete her listing, send her the consent link, submit her for review and follow her stage and your earnings. Base URL: `https://api.creator-guard.com/v1` - [Quickstart — Your first lead in five minutes, in curl, JavaScript or Python.](https://docs.creator-guard.com/quickstart/) - [Leads — Create, list, read, change and withdraw leads.](https://docs.creator-guard.com/leads/) - [Listing & review — Complete her profile, get her confirmations, submit for review.](https://docs.creator-guard.com/listing/) - [API reference — Every endpoint, generated from the OpenAPI 3.1 spec.](https://docs.creator-guard.com/reference/) ## What you need - A **partner account** with Creator Guard. Access is by invitation: [how to become a partner](https://creator-guard.com/for-partners). - Accepted **partner terms** (in the portal, or with [`POST /v1/agreements/{type}/accept`](https://docs.creator-guard.com/reference/#op-acceptAgreement)). - An **API key** (`cg_live_…`, or `cg_test_…` for the [sandbox](https://docs.creator-guard.com/test-mode/)), created in the portal under **Settings → API**. See [API keys](https://docs.creator-guard.com/api-keys/). - A server-side process that sends HTTPS requests. The key must never reach a browser or an app you ship. ## How it works 1. You create a lead with `POST /v1/leads`; we check whether we already know her and answer with her lead (`lead_…`) and creator number (`CR-1047`). 2. You complete her listing, send her the consent link and submit her for review once `next_actions.can_submit_for_review` is `true`. 3. You follow her `stage`, timeline and earnings with `GET` requests, or let [webhooks](https://docs.creator-guard.com/webhooks/) tell you about every change. See [Lead lifecycle](https://docs.creator-guard.com/lead-lifecycle/). The rules are the portal's rules, enforced by Creator Guard for every caller: the API and the portal can never disagree about what is allowed. Every lead tells you in `next_actions` what you can do with it right now. ## Conventions - JSON in and out, UTF-8, at most 1 MB per request body. Times are RFC 3339 in UTC. Money is `{"amount_minor": 150000, "currency": "USD"}`. - Ids are prefixed (`lead_…`, `acct_…`, `req_…`). Treat them as opaque strings. - Unknown request fields are rejected with [`400 unknown_field`](https://docs.creator-guard.com/errors/#unknown_field), unknown query parameters with [`400 unknown_parameter`](https://docs.creator-guard.com/errors/#unknown_parameter). Ignore response fields you do not know. - Every response carries `X-Request-Id` and `X-API-Version`. Quote the request id when you contact [support](https://docs.creator-guard.com/support/). - Retries are safe with [`Idempotency-Key`](https://docs.creator-guard.com/idempotency/); changes are race-safe with [`If-Match`](https://docs.creator-guard.com/leads/#concurrent-changes). ## Machine-readable spec The full contract is published as OpenAPI 3.1 at [`/openapi.yaml`](https://docs.creator-guard.com/openapi.yaml). Import it into Postman, Insomnia or a code generator. --- # Quickstart Source: https://docs.creator-guard.com/quickstart/ From an API key to a lead in your partner portal in about five minutes. > **Important:** > > Try everything with a `cg_test_` key first: it works on the sandbox, never on real data — see [Test mode](https://docs.creator-guard.com/test-mode/). Every request with a **live** key creates or changes a **real lead** under your account. ## 1. Get your API key Create a key yourself in your portal (partner or agency) under **Settings → API**: the portal asks for your second factor (an authenticator app), and a live key needs the [API Terms](https://docs.creator-guard.com/authentication/#api-terms) and the data protection addendum accepted first — see [API keys](https://docs.creator-guard.com/api-keys/). The full key is shown **once**; afterwards only a hash is kept. Store it in your secret store or environment: ```bash export CG_API_KEY="cg_live_…" ``` Check that it works with `GET /v1/me`: the answer names your account and shows in `terms` whether your terms are accepted. Writes need accepted terms (see [Authentication](https://docs.creator-guard.com/authentication/#terms)). ```bash curl https://api.creator-guard.com/v1/me -H "Authorization: Bearer $CG_API_KEY" ``` ## 2. Create a lead The body holds the required fields plus `external_id`, your own reference for this creator. The `Idempotency-Key` header makes a retry after a timeout safe. JavaScript (curl, Python: in the page's Markdown twin): ```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": "@miacreates", "platforms": ["OnlyFans", "Instagram"], "consent_confirmed": true }; 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); ``` ## 3. Read the response A new lead answers **`201 Created`** with the lead object (abridged): ```json { "object": "lead", "id": "lead_hz5ikyc3pnhkrhlb6p7elkx2qy", "external_id": "crm-000042", "creator_ref": "CR-1047", "stage": "draft", "next_actions": { "can_submit_for_review": false, "blockers": ["age_missing", "languages_missing", "country_missing", "content_types_missing", "photos_missing", "consent_missing", "age_confirmation_missing", "fee_missing"] }, "listing": { "status": "draft", "placement_fee": null, "photo_count": 0 }, "consent": { "status": "pending", "url": "https://app.creator-guard.com/creator-consent/…", "expires_at": "2026-11-08T08:00:00Z" } } ``` `200 OK` with the same shape means we already had her: your `external_id` was used before, or your own lead with this Instagram handle is still a draft. See [Duplicates](https://docs.creator-guard.com/leads/#duplicates). An error answers with a `4xx` and an [error body](https://docs.creator-guard.com/errors/). ## 4. Next steps - Send her `consent.url` (shown only in this `201`; later, `POST /v1/leads/{id}/consent-link` makes a new link) and fill in her listing: [Listing & review](https://docs.creator-guard.com/listing/). - Keep your system in step with `GET /v1/leads?updated_since=…`: [Pagination](https://docs.creator-guard.com/pagination/). - Handle every error code: [Errors](https://docs.creator-guard.com/errors/). --- # Authentication Source: https://docs.creator-guard.com/authentication/ Every request except `GET /v1/` carries an API key as a bearer token: ```http Authorization: Bearer cg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` The key identifies your account. Everything you create is attributed to it, so there is no account id in requests. ## Key format A key is `cg_live_` (live mode) or `cg_test_` ([test mode](https://docs.creator-guard.com/test-mode/): same URLs, sandbox data) followed by 43 letters and digits, 51 characters in total. The 43 characters are generated randomly (about 256 bits). The first 12 characters (for example `cg_live_ab12`) are the key's **prefix**: it is stored in clear so you and our team can tell keys apart, and the portal shows it under **Settings → API**. The prefix is distinctive on purpose, so that secret scanners recognise a key that ended up somewhere public. The exact pattern: ```text \bcg_(live|test)_[A-Za-z0-9]{43}\b ``` Add it to your own secret scanning (pre-commit hooks, CI) so a key never reaches a repository in the first place. ### Leaked keys A key that was public must be treated as compromised. When a Creator Guard key is reported to us as public — by you, by anyone else, or by an automated secret scanner such as GitHub's — we revoke it immediately, without asking first. A revoked key cannot be re-enabled. - Requests with the key fail with `401 invalid_key` from the next request on. - The key shows as revoked in your key list, and your audit events (`GET /v1/audit-events`) contain an `api_key.leaked` event with the public URL where it was found, if known. - We email your account's contact address with the key's prefix and label. Create a new key (or ask us for one), switch your system over, and remove the old key from the repository's history. OAuth client secrets (`cgcs_`) and the access and refresh tokens your app holds for creators (`cgo_`, `cgr_`) are watched the same way; what happens then is described under [OAuth](https://docs.creator-guard.com/oauth/). ## Getting a key You create keys yourself in the portal or over the API — see [API keys](https://docs.creator-guard.com/api-keys/); our team can issue them too. Each key has: - a **label** (for example "CRM production"), - **scopes** — what it may do (below), - optionally an **expiry date** (after it: [`401 expired_key`](https://docs.creator-guard.com/errors/#expired_key)), - optionally an **IP allowlist** (below). The full key is shown **once**: in the portal right after you create it, or in `secret` of the API answer. Keys our team issues are handed over through a channel we agree with you (never plain email or chat). Copy it straight into your secret store. Only a SHA-256 hash is kept; if you lose the key, roll it or create a new one and revoke the old one. ## Scopes Each endpoint needs one scope; the [reference](https://docs.creator-guard.com/reference/) names it per operation. A key without it gets [`403 insufficient_scope`](https://docs.creator-guard.com/errors/#insufficient_scope) with `error.scope`. | Scope | Allows | |---|---| | `account:read` | `GET /v1/me`, agreements and their texts, option lists, settings | | `agreements:write` | Accepting agreements | | `leads:read` | Reading leads, listings, confirmations and timelines | | `leads:write` | Creating and changing leads and listings, consent links, submitting for review, withdrawing | | `earnings:read` | `GET /v1/leads/{id}/earnings` | These are the five scopes the portal preselects; all nineteen scopes and what each allows: [API keys](https://docs.creator-guard.com/api-keys/#scopes) and the [Scope](https://docs.creator-guard.com/reference/#schema-Scope) list in the reference. ## IP allowlist A key can be limited to IP addresses or ranges (CIDR, IPv4 and IPv6) — set `ip_allowlist` when you [create the key over the API](https://docs.creator-guard.com/api-keys/#with-the-api), or ask us. A request from anywhere else gets [`403 ip_not_allowed`](https://docs.creator-guard.com/errors/#ip_not_allowed) and does not count against the key's rate limits. ## Terms Reads work with any active account. **Writes** need your account's terms accepted (any version): referrer accounts `referrer_terms`, agency accounts `agency_terms`. Without them a write gets [`403 terms_not_accepted`](https://docs.creator-guard.com/errors/#terms_not_accepted) with `error.agreement_type`. `GET /v1/me` shows the state; accept once in the portal or with [`POST /v1/agreements/{type}/accept`](https://docs.creator-guard.com/reference/#op-acceptAgreement) and the current `version` from [`GET /v1/agreements`](https://docs.creator-guard.com/reference/#op-listAgreements). These writes work before the terms are accepted: | Operation | Endpoint | |---|---| | [`acceptAgreement`](https://docs.creator-guard.com/reference/#op-acceptAgreement) | `POST /v1/agreements/{type}/accept` | | [`createApiKey`](https://docs.creator-guard.com/reference/#op-createApiKey) | `POST /v1/api-keys` | | [`rollApiKey`](https://docs.creator-guard.com/reference/#op-rollApiKey) | `POST /v1/api-keys/{id}/roll` | | [`revokeApiKey`](https://docs.creator-guard.com/reference/#op-revokeApiKey) | `DELETE /v1/api-keys/{id}` | | [`inviteMember`](https://docs.creator-guard.com/reference/#op-inviteMember) | `POST /v1/members` | | [`deleteMember`](https://docs.creator-guard.com/reference/#op-deleteMember) | `DELETE /v1/members/{id}` | | [`extractFields`](https://docs.creator-guard.com/reference/#op-extractFields) | `POST /v1/extract` | | [`testReset`](https://docs.creator-guard.com/reference/#op-testReset) | `POST /v1/test-helpers/reset` (test keys only) | The terms check applies to account API keys only. Requests with a creator's OAuth access token ([creator API](https://docs.creator-guard.com/creator-api/)) are not checked against your account's terms. ## API Terms Using the API is governed by the [API Terms of Use](https://docs.creator-guard.com/legal/api-terms/) (`api_terms`), in addition to your account's terms. Your account accepts them **once**, by an **owner or admin**: in the portal under **Settings → API**, or with [`POST /v1/agreements/api_terms/accept`](https://docs.creator-guard.com/reference/#op-acceptAgreement) and the current `version` from [`GET /v1/agreements`](https://docs.creator-guard.com/reference/#op-listAgreements) (only keys of an owner or admin carry `agreements:write`; a developer or viewer asks one of them). The acceptance counts for live and test keys alike. Any accepted version counts, unless we publish a version marked as needing re-acceptance (announced with [`agreement.published`](https://docs.creator-guard.com/events/) and in the [changelog](https://docs.creator-guard.com/changelog/)). With a **live key**, these need the API Terms — otherwise [`403 terms_not_accepted`](https://docs.creator-guard.com/errors/#terms_not_accepted) with `error.agreement_type: "api_terms"`: - creating or rolling a live key ([`createApiKey`](https://docs.creator-guard.com/reference/#op-createApiKey), [`rollApiKey`](https://docs.creator-guard.com/reference/#op-rollApiKey), in the portal as well), - registering a live OAuth app ([`createOAuthApp`](https://docs.creator-guard.com/reference/#op-createOAuthApp)), - every other write. Always allowed, so a leaked secret can always be stopped: reads, revoking a key ([`revokeApiKey`](https://docs.creator-guard.com/reference/#op-revokeApiKey)), deleting an OAuth app ([`deleteOAuthApp`](https://docs.creator-guard.com/reference/#op-deleteOAuthApp)) or a webhook endpoint ([`deleteWebhookEndpoint`](https://docs.creator-guard.com/reference/#op-deleteWebhookEndpoint)), removing a member ([`deleteMember`](https://docs.creator-guard.com/reference/#op-deleteMember)) and accepting terms. **Test keys** and the sandbox never need the API Terms, and requests with a creator's OAuth access token are never checked against them. **Transition.** An account that already held a live key when the API Terms were published keeps working for **30 days**; the date is in the portal (Settings → API). After it, the rules above apply. An account without a live key at that time accepts them before its first live key. ## Data protection addendum The [data protection addendum](https://docs.creator-guard.com/legal/dpa/) (`api_dpa`) covers the personal data you and we exchange through the API, including the EU Standard Contractual Clauses for transfers to the USA. It works like the API Terms: your account accepts it **once**, by an **owner or admin**, in the portal under **Settings → API** or with [`POST /v1/agreements/api_dpa/accept`](https://docs.creator-guard.com/reference/#op-acceptAgreement), and the acceptance counts for live and test keys. It is needed for the same live actions as the API Terms, with the same exceptions; without it they answer [`403 terms_not_accepted`](https://docs.creator-guard.com/errors/#terms_not_accepted) with `error.agreement_type: "api_dpa"` (when both are missing, `api_terms` is named first). An account that already held a live key when the addendum was published keeps working for **30 days** (the date is in the portal); an account without a live key accepts it before its first one. ## Keep it secret - **Server-side only.** Never in a browser, a mobile or desktop app you ship, or a public repository. The API sends no CORS headers. - Load it from an environment variable or a secret manager. - Send it only to `https://api.creator-guard.com`. ## Revoking a key If a key may have leaked, revoke it in the portal or with [`DELETE /v1/api-keys/{id}`](https://docs.creator-guard.com/api-keys/#revoking) — or tell us and we revoke it at once. Revocation applies to the **very next request** (no cache). To rotate without downtime, [roll the key](https://docs.creator-guard.com/api-keys/#rolling-without-downtime) with a grace period. ## Authentication errors | Status | `code` | When | |---|---|---| | `401` | [`missing_key`](https://docs.creator-guard.com/errors/#missing_key) | No `Authorization: Bearer` header. | | `401` | [`invalid_key`](https://docs.creator-guard.com/errors/#invalid_key) | Unknown or revoked key. | | `401` | [`expired_key`](https://docs.creator-guard.com/errors/#expired_key) | The key is past its expiry date. | | `403` | [`account_not_active`](https://docs.creator-guard.com/errors/#account_not_active) | Your account is pending approval or disabled. | | `403` | [`ip_not_allowed`](https://docs.creator-guard.com/errors/#ip_not_allowed) | The caller's IP is not on the key's allowlist. | | `403` | [`insufficient_scope`](https://docs.creator-guard.com/errors/#insufficient_scope) | The key lacks the endpoint's scope. | | `403` | [`terms_not_accepted`](https://docs.creator-guard.com/errors/#terms_not_accepted) | A write before your terms are accepted — or, with a live key, before the [API Terms](#api-terms) are. | | `503` | [`not_configured`](https://docs.creator-guard.com/errors/#not_configured) | A setting is missing on our side, or test mode is briefly unavailable. | --- # API keys Source: https://docs.creator-guard.com/api-keys/ You manage your keys yourself: in the partner portal under **Settings → API**, or over the API with a key that has `keys:manage`. Our team can still issue and revoke keys for you. ## Two modes | Prefix | Mode | Reaches | |---|---|---| | `cg_live_` | live | Your real leads. | | `cg_test_` | test | The sandbox — see [Test mode](https://docs.creator-guard.com/test-mode/). | Each mode has its own keys, at most **10 active keys per mode** (one more → [`409 limit_reached`](https://docs.creator-guard.com/errors/#limit_reached)). A key only ever sees the data of its own mode. ## Scopes | Scope | Allows | |---|---| | `account:read` | `GET /v1/me`, agreements, option lists, settings, request logs; agencies: your agency profile | | `account:write` | `PATCH /v1/me`, your logo; agencies: `PATCH /v1/agency-profile` | | `agreements:write` | Accepting agreements | | `leads:read` | Leads, listings, photos, confirmations, timelines | | `leads:write` | Creating and changing leads and listings, consent links, review, withdrawing, the test helpers for leads and commissions | | `photos:write` | Uploading, changing and deleting photos | | `earnings:read` | Earnings, commissions, payout details (masked) | | `offers:read` | Agencies: offers and their photos, your search profile | | `offers:write` | Agencies: accepting, declining and progressing offers, your offer notes, the test helpers for offers and the test clock | | `reservations:read` | Agencies: reservations and, once paid, the creator's contact | | `reservations:write` | Agencies: warranty claims, the test helpers for reservations | | `search_profile:write` | Agencies: changing your search profile | | `extract` | `POST /v1/extract` | | `usage:read` | `GET /v1/usage` | | `audit:read` | `GET /v1/audit-events` | | `keys:manage` | `/v1/api-keys`, `POST /v1/test-helpers/reset` | | `webhooks:manage` | `/v1/webhook-endpoints` | | `oauth_apps:manage` | `/v1/oauth-apps`, `POST /v1/test-helpers/oauth-codes` | | `members:manage` | `/v1/members` (live keys only) — see [Members & roles](https://docs.creator-guard.com/members/) | Creating, rolling and revoking keys works before your account has accepted its terms, so you can set up an integration first; most other writes need them — the full list of exceptions is under [Authentication → Terms](https://docs.creator-guard.com/authentication/#terms). A **live** key is different: creating or rolling one needs the [API Terms of Use](https://docs.creator-guard.com/authentication/#api-terms), accepted once by an owner or admin of your account. Test keys never need them, and revoking a key always works. Events (`GET /v1/events`) need no scope of their own: a key sees the events whose object it may read — see [Events](https://docs.creator-guard.com/events/). These nineteen are all scopes there are today; any other value answers [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field) on `scopes`. ## In the portal **Settings → API** lists the keys of both modes. Pick the mode and the permissions when you create one; the five scopes `account:read`, `agreements:write`, `leads:read`, `leads:write` and `earnings:read` are preselected. Creating, rolling and revoking a key and changing the key policy need your **second factor** (an authenticator app): the portal asks for the six-digit code first. Keys made in the portal have no IP allowlist; create a key over the API to set one. ## With the API JavaScript (curl, Python: in the page's Markdown twin): ```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 = { "label": "CRM production", "scopes": ["leads:read", "leads:write", "earnings:read"], "ip_allowlist": ["203.0.113.0/24"] }; const res = await fetch('https://api.creator-guard.com/v1/api-keys', { 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); ``` The answer carries the full key once, in `secret` — store it straight away, it is never shown again. Sending the same request again with the same `Idempotency-Key` answers the same key with `secret: null`. The new key gets the mode of the key that created it and the `scopes` you list — **at most the calling key's own**; asking for more answers [`403 insufficient_scope`](https://docs.creator-guard.com/errors/#insufficient_scope). So `keys:manage` and `webhooks:manage` reach a key made over the API only through a key that already has them, and those come from the portal with your second factor or from our team. `ip_allowlist` takes up to 20 CIDR blocks; `expires_at` is optional. A new key is never less restricted than the key that makes it: - **IP allowlist.** If the calling key has an allowlist, the new key's `ip_allowlist` must lie inside it (each block within one of the caller's blocks) — otherwise [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field) on `ip_allowlist`. Leave it out and the new key gets the caller's allowlist. - **Expiry.** The new key expires no later than the calling key: a later `expires_at`, or none, becomes the caller's expiry. Keys made in the portal are not limited this way. `GET /v1/api-keys` lists the active keys of your mode and those revoked in the last 90 days (prefix, label, scopes, last use, expiry) — never a secret. ## Rolling without downtime `POST /v1/api-keys/{id}/roll` creates a new key with the same label, scopes, IP allowlist and expiry, and keeps the old one working for `grace_hours` (0–72, default 24). It works only for keys whose scopes the calling key holds, and the new key also takes on the calling key's restrictions: its IP allowlist is the overlap of the old key's and the caller's (if both have one and they do not overlap at all → [`409 invalid_state`](https://docs.creator-guard.com/errors/#invalid_state) with `current_state: ip_allowlist_outside_caller`), and it expires no later than the caller. Rolling in the portal keeps the old key's settings as they are. JavaScript (curl, Python: in the page's Markdown twin): ```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 = { "grace_hours": 24 }; const res = await fetch('https://api.creator-guard.com/v1/api-keys/key_hz5ikyc3pnhkrhlb6p7elkx2qy/roll', { 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); ``` Deploy the new secret, then let the grace period run out. The old key shows `grace_until`, the new one `rolled_from`. `grace_hours: 0` revokes the old key at once. As on create, a replay answers `secret: null`. During its grace period the old key keeps working for your data, but it **manages nothing any more**: every request that needs `keys:manage` or `webhooks:manage` answers [`403 insufficient_scope`](https://docs.creator-guard.com/errors/#insufficient_scope) naming that scope. Manage keys and webhooks with the new key. ## Revoking `DELETE /v1/api-keys/{id}` revokes a key; it fails on the very next request, and repeating the call is harmless. Like rolling, it works only for keys whose scopes the calling key holds — otherwise [`403 insufficient_scope`](https://docs.creator-guard.com/errors/#insufficient_scope) naming the first one missing — so a narrow key cannot switch off a wider one. In the portal you can revoke any key. A key revokes itself only with `?force=true` (otherwise [`409 invalid_state`](https://docs.creator-guard.com/errors/#invalid_state) with `current_state: in_use`) — so a script cannot lock itself out by mistake. ## Key policy In **Settings → API → Key policy** (second factor needed) you can set, for the whole account: - **Maximum key age** (1–3,650 days): every key expires that many days after it was created, whatever its own expiry. - **Revoke unused keys** after 30–3,650 days without a request. Off by default. Seven days before a live key expires you get the event [`api_key.expiring`](https://docs.creator-guard.com/events/#event-api_key.expiring), once per key. Every key change — created, rolled, revoked, revoked by the policy — is in the [audit trail](https://docs.creator-guard.com/usage/#audit-trail). --- # Test mode & sandbox Source: https://docs.creator-guard.com/test-mode/ A `cg_test_` key works on the same host and paths as a live key, but every request reaches the **sandbox**: a separate database with its own leads, photos, events and webhook endpoints. Nothing you do there reaches agencies, our team or your live data — and live keys can never see the sandbox. ## Getting a test key Create one in the portal (**Settings → API**, mode **Test**) or with `POST /v1/api-keys` and a test key that has `keys:manage` — see [API keys](https://docs.creator-guard.com/api-keys/). On the first request your account appears in the sandbox by itself, with the same name, type and accepted terms. After that its profile is the sandbox's own: what you change with `PATCH /v1/me` or `/v1/me/logo` and a test key stays in the sandbox and is not overwritten by your live profile (type and accepted terms keep following your live account). ## What is different | | Live | Test | |---|---|---| | Data | Real creators | Made up by you; never use real creator data | | Limits | [Rate limits](https://docs.creator-guard.com/rate-limits/) | **Half** of every limit, rounded up: 50 per minute and 5,000 per day per key, 10 / 100 extractions, 30 / 1,500 uploads | | `POST /v1/extract` | AI suggestions | Always the same fictitious example, no AI | | Photo and logo URLs | Signed storage URLs | `https://api.creator-guard.com/v1/test-files/…?token=…`, also valid for one hour | | Our review, payments | Our team | You, with the test helpers below | | Events | `"mode": "live"` | `"mode": "test"`, sent to the endpoints you registered with a test key | The portal shows and manages **live** webhook endpoints only; register test endpoints with a test key that has `webhooks:manage`. If the sandbox is briefly unavailable, a test key answers [`503 not_configured`](https://docs.creator-guard.com/errors/#not_configured). ## Test helpers They play the parts that Creator Guard or the creator play in live mode. Every helper answers [`404 not_found`](https://docs.creator-guard.com/errors/#not_found) to a live key, before anything happens. | Request | Plays | Result | |---|---|---| | `POST /v1/test-helpers/leads/{id}/confirm` | The creator on her consent page | Consent granted, 18+ confirmed | | `POST /v1/test-helpers/leads/{id}/approve-listing` | Our review | A listing in review goes live; without consent, 18+ confirmation or fee → [`422 not_ready_for_review`](https://docs.creator-guard.com/errors/#not_ready_for_review) | | `POST /v1/test-helpers/leads/{id}/reject` | Our review, body `{"outcome_reason": "duplicate"}` | Lead `rejected` | | `POST /v1/test-helpers/commissions/{id}/mark-paid` | Our payout | A `due` commission becomes `paid` | | `POST /v1/test-helpers/reset` | — | Deletes your test data (see below) | The lead and commission helpers need `leads:write`, the reset `keys:manage`. Each helper sends the same events as the real step, so your webhook handling sees exactly what it will see in live mode. A typical run: create a lead → upload three photos → `confirm` → submit for review → `approve-listing`. Agency keys have their own helpers — a test offer, payment, completion and refund of a reservation, and a test clock: see [Agencies](https://docs.creator-guard.com/agencies/#testing-with-a-test-key). ## Reset `POST /v1/test-helpers/reset` empties the sandbox for your account: every lead, photo, commission, event, delivery, sandbox file and stored `Idempotency-Key` answer. Your test keys, test webhook endpoints and accepted terms stay; the answer counts what was deleted. **Agencies:** the offers and reservations made with the [agency test helpers](https://docs.creator-guard.com/agencies/#testing-with-a-test-key) belong to a sandbox referrer, so a reset leaves them in place (known limit); let them expire with `POST /v1/test-helpers/clock/advance`. ## Going live Nothing moves from test to live. Create a live key, point your integration at the same URLs and register your live webhook endpoints. --- # Referral partner guide Source: https://docs.creator-guard.com/guides/referral-partners/ 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](https://docs.creator-guard.com/test-mode/) 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`](https://docs.creator-guard.com/errors/#terms_not_accepted)), and an account that is pending or disabled gets [`403 account_not_active`](https://docs.creator-guard.com/errors/#account_not_active). JavaScript (curl, Python: in the page's Markdown twin): ```js 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'}`); ``` Accept the terms once — in the portal, or with the current `version` from `GET /v1/agreements`: JavaScript (curl, Python: in the page's Markdown twin): ```js 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}`); ``` What each scope allows: [Authentication](https://docs.creator-guard.com/authentication/#scopes). 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. JavaScript (curl, Python: in the page's Markdown twin): ```js 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); ``` `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`](https://docs.creator-guard.com/errors/#duplicate_other_referrer). All cases: [Duplicates](https://docs.creator-guard.com/leads/#duplicates) and [Idempotency & retries](https://docs.creator-guard.com/idempotency/). ## 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`](https://docs.creator-guard.com/errors/#precondition_failed) — read again and retry). JavaScript (curl, Python: in the page's Markdown twin): ```js 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(', ')); ``` Upload three photos with `POST /v1/leads/{id}/photos` (multipart, field `file`): see [Photos](https://docs.creator-guard.com/photos/). Every field and the fee: [Listing & review](https://docs.creator-guard.com/listing/#fields). ## 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): JavaScript (curl, Python: in the page's Markdown twin): ```js 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); ``` 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`](https://docs.creator-guard.com/errors/#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. JavaScript (curl, Python: in the page's Markdown twin): ```js 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(', ')}`); ``` ## 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](https://docs.creator-guard.com/lead-lifecycle/). You see milestones, never agency names. - **Push:** subscribe to `lead.stage_changed` and the other lead events with a [webhook](https://docs.creator-guard.com/webhooks/). - **Pull:** list what changed since your last sync with `updated_since` — [Pagination & sync](https://docs.creator-guard.com/pagination/#keeping-in-sync). JavaScript (curl, Python: in the page's Markdown twin): ```js 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)`); ``` `GET /v1/leads/{id}` returns one lead; `?expand=listing,photos,confirmations` adds those objects. `GET /v1/leads/{id}/timeline` lists her milestones. JavaScript (curl, Python: in the page's Markdown twin): ```js 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); ``` ## 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](https://docs.creator-guard.com/account/). ## 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 (Python: in the page's Markdown twin): ```js 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); ``` The [SDKs](https://docs.creator-guard.com/sdks/) do all of this for you. All codes: [Errors](https://docs.creator-guard.com/errors/). Limits: [Rate limits](https://docs.creator-guard.com/rate-limits/). --- # Agency guide Source: https://docs.creator-guard.com/guides/agencies/ As an agency you receive **offers**: creators Creator Guard matched to your search profile. This guide takes one offer from the moment it arrives to the signed creator, with runnable samples in curl, JavaScript and Python. Every status, field and rule is on [Agencies: offers & reservations](https://docs.creator-guard.com/agencies/). Matching stays with Creator Guard: you see your offers, never the marketplace. Offers with a creator's profile reach your account only after your agency passed our vetting; GET /v1/agency-profile shows the state. Build it with a `cg_test_` key first: [test helpers](https://docs.creator-guard.com/agencies/#testing-with-a-test-key) create offers for you and play our payment and warranty steps. ## 1. Key and terms Use an **agency key**; a referral partner's key gets [`403 wrong_account_type`](https://docs.creator-guard.com/errors/#wrong_account_type) on every agency endpoint. Writes need the current `agency_terms`, and accepting an offer also the current `warranty_terms` — without them [`403 terms_not_accepted`](https://docs.creator-guard.com/errors/#terms_not_accepted) names the missing `agreement_type`. Read the versions with `GET /v1/agreements` and accept with `POST /v1/agreements/{type}/accept`. ## 2. Keep your search profile current `GET /v1/search-profile` returns what we match creators against; `PUT /v1/search-profile` replaces it as a whole, so read it, change what you need and send the whole object back. `flex` says per criterion how far a creator may deviate: [Search profile](https://docs.creator-guard.com/agencies/#search-profile-and-agency-profile). ## 3. Read your offers React to `offer.created` with a [webhook](https://docs.creator-guard.com/webhooks/), or list your open offers: JavaScript (curl, Python: in the page's Markdown twin): ```js const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com'; const res = await fetch(`${BASE}/v1/offers?status=offered&limit=100`, { 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}`); for (const offer of page.data) console.log(offer.id, offer.creator_ref, 'answer by', offer.expires_at); if (page.has_more) console.log('more: pass next_cursor as starting_after'); ``` An open offer shows her name and creator number (`CR-…`), the listing with the deal and the fee, and `expires_at`. Her contact data follows only after payment. `GET /v1/offers/{id}/photos` returns the photos she agreed to share, as links valid for 1 hour. JavaScript (curl, Python: in the page's Markdown twin): ```js 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 [first] = (await get('/v1/offers?limit=1')).data; if (!first) throw new Error('no offers yet'); const offer = await get(`/v1/offers/${first.id}`); console.log(offer.id, offer.creator_ref, offer.status, 'expires', offer.expires_at); ``` Every offer carries `next_actions`, so you never have to re-implement which step is allowed when. Every offer also carries `match`: how well she fits your [search profile](#2-keep-your-search-profile-current), as `score` of `total` criteria (a close match counts ½; sort by `score` / `total`) and `knocked_out` when a must-match criterion is missed. It names criteria (`languages`, `niche`, …) and results only, never her values, and is `null` while you have no search profile. ## 4. Accept or decline `POST /v1/offers/{id}/accept` reserves her for you and creates a reservation awaiting payment. Only one agency can win her: [`409 offer_taken`](https://docs.creator-guard.com/errors/#offer_taken) means another agency was first, [`409 offer_expired`](https://docs.creator-guard.com/errors/#offer_expired) that the deadline passed, [`409 listing_unavailable`](https://docs.creator-guard.com/errors/#listing_unavailable) that her listing was taken off the market. JavaScript (curl, Python: in the page's Markdown twin): ```js const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com'; const headers = { Authorization: `Bearer ${process.env.CG_API_KEY}` }; const list = await fetch(`${BASE}/v1/offers?status=offered&limit=1`, { headers }); const [offer] = (await list.json()).data ?? []; if (!offer) throw new Error('no open offer'); const res = await fetch(`${BASE}/v1/offers/${offer.id}/accept`, { method: 'POST', headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() }, }); const data = await res.json(); let outcome; if (res.ok) outcome = data.status; // reserved: pay the reservation before the due date else if (['offer_taken', 'offer_expired', 'listing_unavailable'].includes(data.error.code)) outcome = data.error.code; else if (data.error.code === 'terms_not_accepted') outcome = `accept ${data.error.agreement_type} first`; else throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`); console.log(offer.id, '→', outcome); ``` Changed your mind? `POST /v1/offers/{id}/undo-accept` works for a few minutes after accepting (`undo_until`) and only before payment. Not a fit? `POST /v1/offers/{id}/decline` with a `note` of 50–500 characters. ## 5. Pay the reservation Payment happens outside the API: transfer the `amount` with the `payment_reference` before `payment_due_at`. When we have it, the reservation becomes `paid` and you receive `reservation.paid`. ## 6. Reach her and report progress Once the reservation is paid, `GET /v1/reservations/{id}/creator` returns her name, Instagram, other contact, platforms, followers, niche and creator number; before payment it answers [`409 payment_pending`](https://docs.creator-guard.com/errors/#payment_pending). You never learn who referred her. Report what happens with `POST /v1/offers/{id}/mark-contacted`, `POST /v1/offers/{id}/mark-in-talks`, `POST /v1/offers/{id}/mark-signed` or `POST /v1/offers/{id}/mark-lost` (with an `outcome_reason`; only before you paid — after payment it answers `409 deal_paid`, and a warranty claim is the way out). ## 7. Warranty claim While the warranty runs (`warranty_until` on the reservation) you can file **one** claim with `POST /v1/reservations/{id}/warranty-claim`, giving a `reason`. A second claim answers [`409 claim_exists`](https://docs.creator-guard.com/errors/#claim_exists), one after the warranty [`409 warranty_expired`](https://docs.creator-guard.com/errors/#warranty_expired). Reasons and outcomes: [Reservations](https://docs.creator-guard.com/agencies/#reservations). ## Keep in step Subscribe to the `offer.*`, `reservation.*` and `warranty_claim.created` events ([Webhooks](https://docs.creator-guard.com/webhooks/)); they fire the same way whether you act in the portal or through the API. Agencies refer creators too: [Referral partner guide](https://docs.creator-guard.com/guides/referral-partners/). The [SDKs](https://docs.creator-guard.com/sdks/) handle retries, idempotency keys and pagination for you. --- # Creator dashboards Source: https://docs.creator-guard.com/guides/creator-dashboards/ Every creator you submit has steps only she can take: consent to be introduced to agencies, confirm she is 18 or older, check her profile and follow her placement. You choose where she takes them: | | Hosted pages | Your own dashboard | |---|---|---| | You build | nothing: you send her links | an OAuth app and your own screens | | She signs in | on `app.creator-guard.com` | on our sign-in page with her own login, to approve your app | | She uses | the consent page and the creator portal | your screens, backed by the creator API | | The consent text | we show it | you show the exact versioned text we give you | Both ways record the same evidence for every decision in her [consent ledger](https://docs.creator-guard.com/consent-ledger/), and she can always use the creator portal as well. ## Hosted pages 1. **Consent link.** `POST /v1/leads/{id}/consent-link` returns her personal consent page. She reads the text, confirms she is 18 or older and agrees or declines. JavaScript (curl, Python: in the page's Markdown twin): ```js 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); ``` 2. **Claim link.** `POST /v1/leads/{id}/claim-link` returns a link, valid for 7 days and usable once, where she chooses her own email address and password for the creator portal. Nobody else ever sets or learns her password. 3. She signs in to the creator portal to see her status, edit her profile, manage her photos, give or withdraw her consent and contact support. Follow the result with `GET /v1/leads/{id}/confirmations` or the `consent.granted`, `consent.revoked` and `age_confirmation.confirmed` [webhook events](https://docs.creator-guard.com/webhooks/). Details: [Hosted pages](https://docs.creator-guard.com/hosted-pages/). ## Your own dashboard 1. Register an OAuth app with `POST /v1/oauth-apps` and ask only for the scopes your screens need. 2. Send her through the authorization flow (PKCE `S256`) described in [OAuth](https://docs.creator-guard.com/oauth/). She can connect your app only if your account referred her or holds a paid reservation for her. 3. Call the [creator API](https://docs.creator-guard.com/creator-api/) with her access token — for example her current status: JavaScript (curl, Python: in the page's Markdown twin): ```js const BASE = process.env.CG_API_BASE ?? 'https://api.creator-guard.com'; // The creator's access token from the OAuth flow (1 hour); refresh it with her refresh token at /oauth/token. const res = await fetch(`${BASE}/v1/creator/me`, { headers: { Authorization: `Bearer ${process.env.CG_API_KEY}` } }); const me = await res.json(); if (res.status === 401) throw new Error(`token ${me.error.code}: refresh it, or ask her to connect again`); if (!res.ok) throw new Error(`${res.status} ${me.error.code}: ${me.error.message}`); console.log('stage:', me.stage, 'blockers:', (me.next_actions.blockers ?? []).join(', ') || 'none'); ``` Her password, email address and sign-in stay on our hosted pages; no app can change them. ## Her consent stays hers - `consent_confirmed: true` on a new lead is **your** statement that she agreed to be submitted. It does not release her photos to agencies; only her own consent does. - **Only she grants or withdraws consent**, on the consent page, in the creator portal or through her own action in your app. Never call the consent endpoints without her doing so. - **Show the current text, unchanged.** Fetch it with `GET /v1/creator/consent-text`, show it in full and send its `version` with her decision. An outdated version answers [`409 consent_text_outdated`](https://docs.creator-guard.com/errors/#consent_text_outdated) and records nothing: show her the new text and ask again. - **She can withdraw at any time**, and a withdrawal is never refused because of the text version. She can also disconnect your app in the creator portal; your tokens then stop working. --- # Webhooks Source: https://docs.creator-guard.com/webhooks/ Instead of asking `GET /v1/leads?updated_since=…` every few minutes, let us call you: a webhook endpoint receives a `POST` for every [event](https://docs.creator-guard.com/events/) it subscribes to, within seconds. ## Add an endpoint In the portal (**Settings → API → Webhooks**, second factor needed) or with a key that has `webhooks:manage`: JavaScript (curl, Python: in the page's Markdown twin): ```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 = { "url": "https://hooks.example.com/creator-guard", "event_types": ["lead.stage_changed", "consent.granted", "commission.paid"], "description": "CRM sync" }; const res = await fetch('https://api.creator-guard.com/v1/webhook-endpoints', { 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); ``` `event_types` lists the types you want, or `["*"]` for all of them. The answer contains the signing secret (`whsec_…`) **once** — store it next to your API key. If you send the same request again with the same `Idempotency-Key`, the replayed answer has `secret: null`; the secret of the first answer is the one that counts. **An endpoint carries only what its key may read.** The event types you subscribe to must be readable with the scopes of the key that creates (or changes) the endpoint — `lead.*`, `listing.approved`, `photo.*`, `consent.*` and `age_confirmation.confirmed` need `leads:read`, `commission.*` needs `earnings:read`, `agreement.published` needs `account:read`, `api_key.expiring` needs `keys:manage`; otherwise [`403 insufficient_scope`](https://docs.creator-guard.com/errors/#insufficient_scope) naming the scope. With `["*"]` the endpoint gets every type the key can read, nothing more — also later, and also on [replay](#replay). When a key changes the URL or the event types of an endpoint, the endpoint from then on carries only what that key can read; deliveries still waiting that it may no longer carry end as `failed` with `last_error: scope_removed`. This holds on every send: a delivery the endpoint may no longer carry is never sent — it ends `failed` (`scope_removed`) when it is next due, and a [retry](#retries) of it answers [`409 invalid_state`](https://docs.creator-guard.com/errors/#invalid_state). Endpoints set up in the portal (second factor) carry everything. Rules for the URL: `https`, port 443, no user name or password in it, and a host that resolves to public addresses only. We check it now (a host we cannot look up answers [`502 upstream_failed`](https://docs.creator-guard.com/errors/#upstream_failed)) and again before every delivery. At most **10 endpoints per mode** ([`409 limit_reached`](https://docs.creator-guard.com/errors/#limit_reached)). The portal manages **live** endpoints only. Test-mode endpoints are created with a `cg_test_` key and only get test events — see [Test mode](https://docs.creator-guard.com/test-mode/). `POST /v1/webhook-endpoints/{id}/test` sends a [`ping`](https://docs.creator-guard.com/events/#event-ping) to this endpoint only — the quickest way to try your signature check. ## Change or delete an endpoint `PATCH /v1/webhook-endpoints/{id}` changes `url`, `event_types`, `description` or `enabled`; a new URL is checked like on create. Every endpoint answer carries an `ETag`: send it back in `If-Match` and the change is refused with [`412 precondition_failed`](https://docs.creator-guard.com/errors/#precondition_failed) if someone else changed the endpoint in the meantime. `DELETE /v1/webhook-endpoints/{id}` removes the endpoint, its deliveries and every delivery still waiting for it. ## What we send A test send, exactly as your server receives it: ```http POST /creator-guard HTTP/1.1 Content-Type: application/json User-Agent: CreatorGuard-Webhooks/1.0 CG-Event-Id: evt_aaaaaaaaaaaaaaaaaaaaaaaaaa CG-Event-Type: ping CG-Delivery-Id: whd_c7x2m4qk3vbn5h6tjd2wle4pza CG-Signature: t=1791360000,v1=ac0772a3a4acdcc2fd2043ab9f18fc89e798aeb5efe9f79e5d1b3240413b7c29 {"id":"evt_aaaaaaaaaaaaaaaaaaaaaaaaaa","object":"event","type":"ping","created_at":"2026-10-07T08:00:00Z","mode":"test","api_version":"1.6.0","sequence":0,"data":{"object":{}}} ``` That signature is valid for the secret `whsec_0123456789abcdef0123456789abcdef0123456789abcdef` — our test vector, also used by the samples below. A real event carries the object it is about: ```json { "id": "evt_hz5ikyc3pnhkrhlb6p7elkx2qy", "object": "event", "type": "lead.stage_changed", "created_at": "2026-10-10T08:00:00Z", "mode": "live", "api_version": "1.6.0", "sequence": 7, "data": { "object": { "object": "lead", "id": "lead_hz5ikyc3pnhkrhlb6p7elkx2qy", "stage": "ready", "version": 7 } }, "previous_attributes": { "stage": "in_review" } } ``` `data.object` is the full object (shortened above) as your account may see it **when we deliver** — fetch it again only if you need more. Every request comes from **37.187.128.185** (since 5 November 2026; before: 187.127.76.75); allow that address if your firewall needs one. ## Check the signature `CG-Signature` holds a timestamp `t` and one `v1` per active secret: the hex HMAC-SHA256 of `"."` with your whole secret string (`whsec_…`) as the key. Accept a request only if one `v1` matches **and** `t` is at most 5 minutes old. Use the **raw** body exactly as received — parsing and re-serialising the JSON changes the bytes and the signature no longer matches. JavaScript (webhooks/verify.mjs): ```js // Verify a Creator Guard webhook (Node.js 18+, no dependencies). // rawBody: the request body exactly as received (string or Buffer) — not re-serialised JSON. // header: the CG-Signature header. secret: your endpoint's whsec_… secret. import { createHmac, timingSafeEqual } from 'node:crypto'; export const TOLERANCE_SECONDS = 300; export function verifyWebhook(rawBody, header, secret, now = Math.floor(Date.now() / 1000)) { let timestamp = null; const signatures = []; for (const part of String(header ?? '').split(',')) { const [key, value] = part.trim().split('=', 2); if (key === 't' && /^\d+$/.test(value ?? '')) timestamp = Number(value); if (key === 'v1' && /^[0-9a-f]{64}$/.test(value ?? '')) signatures.push(Buffer.from(value, 'hex')); } if (timestamp === null || signatures.length === 0) return false; if (Math.abs(now - timestamp) > TOLERANCE_SECONDS) return false; // too old (or clock far off): a replay const expected = createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest(); // One v1 per active secret: during a rotation we sign with the new and the old one. return signatures.some((signature) => timingSafeEqual(signature, expected)); } ``` Python (webhooks/verify.py): ```python # Verify a Creator Guard webhook (Python 3.8+, standard library only). # raw_body: the request body exactly as received (bytes) — not re-serialised JSON. # header: the CG-Signature header. secret: your endpoint's whsec_… secret. import hashlib import hmac import re import time TOLERANCE_SECONDS = 300 def verify_webhook(raw_body, header, secret, now=None): if isinstance(raw_body, str): raw_body = raw_body.encode("utf-8") timestamp, signatures = None, [] for part in (header or "").split(","): key, _, value = part.strip().partition("=") if key == "t" and value.isdigit(): timestamp = int(value) if key == "v1" and re.fullmatch(r"[0-9a-f]{64}", value): signatures.append(value) if timestamp is None or not signatures: return False now = int(time.time()) if now is None else now if abs(now - timestamp) > TOLERANCE_SECONDS: # too old (or clock far off): a replay return False expected = hmac.new(secret.encode("utf-8"), f"{timestamp}.".encode("utf-8") + raw_body, hashlib.sha256).hexdigest() # One v1 per active secret: during a rotation we sign with the new and the old one. return any(hmac.compare_digest(signature, expected) for signature in signatures) ``` With Express, read the raw body for this route only: ```js import express from 'express'; import { verifyWebhook } from './verify.mjs'; const app = express(); app.post('/creator-guard', express.raw({ type: 'application/json' }), (req, res) => { if (!verifyWebhook(req.body, req.get('CG-Signature'), process.env.CG_WEBHOOK_SECRET)) return res.sendStatus(400); res.sendStatus(200); // answer first, then work: we wait at most 10 seconds jobs.push(JSON.parse(req.body.toString('utf8'))); // your own job queue }); ``` The [SDKs](https://docs.creator-guard.com/sdks/#webhook-signatures) have the same check built in (`verifyWebhookSignature` in TypeScript, `verify_webhook_signature` in Python); both are tested against the request above. ## Roll the secret `POST /v1/webhook-endpoints/{id}/roll` (or **Roll secret** in the portal) issues a new secret, again shown once. For **24 hours** we sign with the new and the old one (two `v1` values), so you can switch without losing a delivery. We keep at most two secrets: roll again within those 24 hours and the newest two sign (the one before them stops at once), each roll starting a fresh 24 hours for its predecessor — so finish switching to one secret before you roll the next. ## Answer fast, process later Any `2xx` within **10 seconds** counts as delivered. Everything else — another status, a timeout, a refused connection — is retried. Store the event, answer `200`, then do the work. ## Retries At least once: a delivery is retried until it succeeds or 72 hours have passed. Minutes after the first attempt: | Attempt | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | |---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---| | Minute | 0 | 1 | 5 | 15 | 30 | 60 | 120 | 240 | 480 | 720 | 1080 | 1440 | 2160 | 2880 | 3600 | 4320 | After the 16th attempt the delivery is `failed`. A failure on our side (we could not prepare the event) does not use up an attempt: it is tried again with a growing pause, at most hourly, and ends `failed` with `last_error: internal_error` once it is past the 72 hours — without counting toward disabling the endpoint. An endpoint whose deliveries have failed without a break for **72 hours** is disabled (`disabled_reason: failing`), and the event [`webhook_endpoint.disabled`](https://docs.creator-guard.com/events/#event-webhook_endpoint.disabled) goes to your other endpoints and into `GET /v1/events`. Fix the receiver, then `PATCH` it with `{"enabled": true}` — that starts its failure clock afresh. `GET /v1/webhook-endpoints/{id}/deliveries` lists the deliveries of the last 30 days, newest first, each with every attempt (status code, duration, error); it pages forward only, with `starting_after`. `POST /v1/webhook-endpoints/{id}/deliveries/{d}/retry` makes one due again at once — also one that has already `failed`. ## Duplicates and order - **Duplicates happen** (at least once): skip an event whose `CG-Event-Id` you have already processed. - **Order is not guaranteed.** Every lead, photo and commission carries `version`, and every event about it carries the version the object reached as `sequence`. Keep the highest `sequence` you applied per object and drop an event with a lower or equal one. ## Replay `POST /v1/webhook-endpoints/{id}/replay` with `{"from": "…", "to": "…"}` (`to` defaults to now) sends every event of that range again that the endpoint subscribes to — at most 30 days back. An endpoint holds at most **1,000 open deliveries** (waiting or being sent) after a replay: a range that would pass that is refused whole with [`409 limit_reached`](https://docs.creator-guard.com/errors/#limit_reached) (`limit: 1000`) and nothing is queued — wait for the queue to drain or pick a shorter range. Replays are spread out (four per second) and at most **10 per account and day** (test mode: 5) → [`429 rate_limited`](https://docs.creator-guard.com/errors/#rate_limited). Replayed deliveries have `replay: true`; your `sequence` check drops what you already have. Use it after an outage longer than 72 hours, or to fill a new database. Deliveries are shared fairly: we send at most 5 deliveries to one endpoint at the same time and take turns between endpoints, so a long replay to one endpoint never holds up the events of another. --- # Build with AI agents Source: https://docs.creator-guard.com/ai-agents/ These docs are published for AI coding agents as well as for people. Give your agent the right file and the rules below, and it can write a working integration against the sandbox in one go. ## What to give your agent | File | What it is | Use it for | |---|---|---| | [`/llms-full.txt`](https://docs.creator-guard.com/llms-full.txt) | The complete documentation as one Markdown file (about 500 KB): every guide page in sidebar order and the full API reference rendered from the contract — every operation with its scopes and account types, every schema, error code, limit and event type. | The default. Put it into the agent's context or let it read the file. | | [`/llms.txt`](https://docs.creator-guard.com/llms.txt) | A short index ([llmstxt.org](https://llmstxt.org) format) linking the Markdown version of every page. | Agents that fetch only the pages they need. | | [`/openapi.yaml`](https://docs.creator-guard.com/openapi.yaml) | The contract, OpenAPI 3.1. | Code generators, typed clients, request validation in your tests. | | `/.md` | Every page as Markdown, e.g. [`/quickstart.md`](https://docs.creator-guard.com/quickstart.md). Each page has **Copy page for AI**, **Open in Claude** and **Open in ChatGPT** buttons under its title. | One topic at a time. | The [SDKs](https://docs.creator-guard.com/sdks/) (TypeScript, Python) and the Postman / Bruno collections are generated from the same contract; an agent may use them instead of raw HTTP. ## Claude Code, Cursor and other coding agents 1. Download the full docs into your project, so the agent reads them like any other file: `curl -o docs/creator-guard.md https://docs.creator-guard.com/llms-full.txt` (and `openapi.yaml` next to it if you generate code). 2. Put your **test key** (`cg_test_…`) into the environment the agent's code reads (`CG_API_KEY`), never into the prompt or a file in the repository. 3. Start the agent with the prompt below, then describe your task. In Cursor, add the docs as a documentation source (`https://docs.creator-guard.com/llms-full.txt`) or reference the downloaded file with `@`. In Claude Code, reference the file (`@docs/creator-guard.md`) or keep the rules in your project's `CLAUDE.md`. ## ChatGPT, Claude and other chat assistants Use **Open in ChatGPT** or **Open in Claude** on any page: it opens a new chat with a prompt that points to that page's Markdown. For a whole integration, upload `llms-full.txt` to the chat (or paste its URL if the assistant can read web pages) together with the prompt below. ## Prompt for your agent Copy it as it is; it holds only facts from these docs and no secrets. ```text You are building an integration with the Creator Guard Platform API (Beta). Documentation: https://docs.creator-guard.com/llms-full.txt (complete) and https://docs.creator-guard.com/openapi.yaml (OpenAPI 3.1 contract). Follow them; do not guess fields or endpoints. Basics - Base URL: https://api.creator-guard.com/v1 — JSON in and out, UTF-8, at most 1 MB per request body. The code samples in the docs read CG_API_BASE as the host WITHOUT /v1 (default https://api.creator-guard.com) and append /v1/… themselves; keep one convention so you never call /v1/v1/…. - Auth: header "Authorization: Bearer ". Read the key from the environment variable CG_API_KEY. Never hard-code it, never log it, never send it to a browser or ship it in an app. - Sandbox: cg_test_ keys use the SAME base URL and paths; they reach a separate sandbox (made-up data only, half of every rate limit, test helpers under /v1/test-helpers/). Build and test everything with a cg_test_ key first. A cg_live_ key creates and changes real data. - Check the key with GET /v1/me: account type (referral partner or agency), terms state, limits. Writes - Every POST gets an Idempotency-Key header (e.g. a UUID). Generate it once per operation, store it, and send the same key with the same body bytes on every retry (store key and body until a final answer). A replayed answer carries Idempotent-Replayed: true. 409 idempotency_in_progress = wait and retry; 422 idempotency_key_reused = you changed the request, use a new key. - POST /v1/leads: send your own external_id — creating the same external_id again returns that lead (200). - consent_confirmed must be exactly true and means the creator agreed to be referred and to her data being sent. Only send it when that is true. - Duplicates by Instagram handle: 409 duplicate_own_lead (your lead, see error.lead) or 409 duplicate_other_referrer (another account has her). Do not retry these; report them. The duplicate answers are budgeted (20 per rolling 24 hours, then 429 duplicate_limit_reached). - To avoid lost updates, send the ETag you read as If-Match on PATCH; 412 precondition_failed = read again. - Writes need accepted terms; otherwise 403 terms_not_accepted with error.agreement_type. With a live key that includes the API Terms (api_terms) and the data protection addendum (api_dpa), each accepted once per account by an owner or admin. Do not accept terms in code on the user's behalf unless they told you to. Errors, limits, pagination - Every error is {"error": {"type", "code", "message", "field", "details", "doc_url", "request_id"}}. Branch on error.code (stable), never on message. Log error.request_id. A 502 or 504 without a JSON body comes from the gateway during a restart: do not assume every answer parses as JSON. - Limits per key: 100 requests per minute and 10,000 per day, 25 in flight. Read the RateLimit header. On 429 wait the Retry-After seconds and pause the whole queue. - Retry only network errors, timeouts, 409 idempotency_in_progress, 429 and 5xx — with the same Idempotency-Key, using Retry-After or exponential backoff. Never retry other 4xx unchanged: fix the request. - Lists: limit 1-100 (default 25), newest first; pass next_cursor as starting_after until has_more is false. - Unknown request fields or query parameters are rejected (400 unknown_field / unknown_parameter); ignore response fields you do not know. Webhooks - Verify every delivery: CG-Signature is "t=,v1=" (one v1 per active secret). Compute HMAC-SHA256 of "." with the whole secret (whsec_…) as key, compare in constant time with a v1, and accept only if t is at most 5 minutes old. Use the raw body bytes, not re-serialised JSON. - Store the event and answer 2xx within 10 seconds, process later. Deliveries are at least once and not in order: skip a CG-Event-Id you already processed, and per object drop an event whose sequence is not higher than the one you applied. Never - Never record a creator's consent, 18+ confirmation or terms through an app of the account that referred her (403 referrer_app_not_allowed). She gives them only on Creator Guard's own pages — send her the consent link (consent.url of the 201, or POST /v1/leads/{id}/consent-link). - Never put real creator data into the sandbox, and never use made-up data with a live key. - Never store keys, webhook secrets or creator access tokens in source code, prompts or logs. - Never work around rate limits, duplicate rules or the review: they are the platform's rules. ``` ## Rules behind the prompt Each line of the prompt comes from a page of these docs: - Keys, scopes and the API Terms: [Authentication](https://docs.creator-guard.com/authentication/), [API keys](https://docs.creator-guard.com/api-keys/) - The sandbox and its helpers: [Test mode & sandbox](https://docs.creator-guard.com/test-mode/) - Retries: [Idempotency & retries](https://docs.creator-guard.com/idempotency/); duplicates and `If-Match`: [Leads](https://docs.creator-guard.com/leads/#duplicates) - [Errors](https://docs.creator-guard.com/errors/), [Rate limits](https://docs.creator-guard.com/rate-limits/), [Pagination & sync](https://docs.creator-guard.com/pagination/) - [Webhooks](https://docs.creator-guard.com/webhooks/#check-the-signature) — the SDKs ship the signature check - What `consent_confirmed` declares and how she confirms herself: [Data protection](https://docs.creator-guard.com/data-protection/), [Creator API](https://docs.creator-guard.com/creator-api/#consent-and-18) ## Check what the agent built - Run it against the sandbox with a `cg_test_` key and play our part with the [test helpers](https://docs.creator-guard.com/test-mode/#test-helpers): `confirm` the lead, then `approve-listing`. - Make it send the same create twice with the same `Idempotency-Key`: the second answer must be the first one, with `Idempotent-Replayed: true`. - Send a webhook test (`POST /v1/webhook-endpoints/{id}/test`) and check that the signature check accepts it — and refuses the same body with one byte changed. - Search the code and its git history for `cg_live_` and `cg_test_`: a key must never be there (the [key pattern](https://docs.creator-guard.com/authentication/#key-format) works in secret scanners). --- # Leads Source: https://docs.creator-guard.com/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 JavaScript (curl, Python: in the page's Markdown twin): ```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); ``` 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/`, 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.`. | 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. --- # Listing & review Source: https://docs.creator-guard.com/listing/ 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 JavaScript (curl, Python: in the page's Markdown twin): ```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 = { "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); ``` 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`](https://docs.creator-guard.com/errors/#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`](https://docs.creator-guard.com/errors/#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](https://docs.creator-guard.com/leads/#concurrent-changes): a stale value → [`412 precondition_failed`](https://docs.creator-guard.com/errors/#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](https://docs.creator-guard.com/reference/#schema-ListingPatch). | Group | Fields | |---|---| | Profile | `age` (18–99, below 18 → [`age_below_18`](https://docs.creator-guard.com/errors/#age_below_18)), `gender`, `origin_country`, `languages` ([pick-list values](https://docs.creator-guard.com/leads/#pick-list-values)), `english_level` (1–10) | | Content | `content_types` ([pick-list values](https://docs.creator-guard.com/leads/#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](https://docs.creator-guard.com/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`](https://docs.creator-guard.com/errors/#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`](https://docs.creator-guard.com/errors/#not_ready_for_review) with `error.blockers`; a lead that is not a draft answers [`409 invalid_state`](https://docs.creator-guard.com/errors/#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`](https://docs.creator-guard.com/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`](https://docs.creator-guard.com/reference/#op-getSettings). --- # Photos Source: https://docs.creator-guard.com/photos/ A lead needs **three photos** before review (`photos_missing` in `next_actions.blockers`). Upload them with the API or in the portal; both end up in the same place. ## Upload `POST /v1/leads/{id}/photos` with `multipart/form-data` (scope `photos:write`): | Part | Required | Value | |---|---|---| | `file` | yes | JPEG, PNG or WebP; at most **40 MB** and 50 megapixels; exactly one file | | `kind` | no | `portrait` (default), `body`, `content_sample`, `non_nude`, `lingerie` or `professional` | | `is_primary` | no | `true` makes it her primary photo; her first photo always is | ```bash curl -X POST https://api.creator-guard.com/v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy/photos \ -H "Authorization: Bearer $CG_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -F "file=@portrait.jpg" \ -F "kind=portrait" ``` ```js // Node.js 20+: fetch, FormData and Blob are built in. import { readFile } from 'node:fs/promises'; const form = new FormData(); form.append('file', new Blob([await readFile('portrait.jpg')], { type: 'image/jpeg' }), 'portrait.jpg'); form.append('kind', 'portrait'); const res = await fetch('https://api.creator-guard.com/v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy/photos', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CG_API_KEY}`, 'Idempotency-Key': crypto.randomUUID() }, body: form, // fetch sets the multipart Content-Type with its boundary }); ``` ```python import os, uuid, requests with open("portrait.jpg", "rb") as f: res = requests.post( "https://api.creator-guard.com/v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy/photos", headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}, files={"file": ("portrait.jpg", f, "image/jpeg")}, data={"kind": "portrait"}, timeout=60, ) ``` The answer (`201`) is the photo: `id`, `lead`, `kind`, `is_primary`, `consent_status`, a signed `url` (valid one hour, until `url_expires_at`), `created_at` and `version`. A replay of the same `Idempotency-Key` answers the same photo with `url` and `url_expires_at` as `null` — list the photos for a fresh URL. ## What we do with every file Before anything is stored we read the format from the bytes, decode the image, **bake in its orientation**, scale it to at most 3000 px on the long edge and re-encode it **without any metadata** — no EXIF, no GPS position, no XMP, no IPTC. A second check rejects the result if any metadata block survived. Neither your original bytes nor the file name are stored. A file we cannot decode answers [`422 image_unreadable`](https://docs.creator-guard.com/errors/#image_unreadable); another format [`415 unsupported_media_type`](https://docs.creator-guard.com/errors/#unsupported_media_type); a larger one [`413 payload_too_large`](https://docs.creator-guard.com/errors/#payload_too_large). ## Limits - At most **20 photos per lead** ([`409 limit_reached`](https://docs.creator-guard.com/errors/#limit_reached)). - Uploads (photos and logos together) count **60 per minute and 3,000 per day per account**, on top of the [request limits](https://docs.creator-guard.com/rate-limits/) and halved in [test mode](https://docs.creator-guard.com/test-mode/); over it: [`429 rate_limited`](https://docs.creator-guard.com/errors/#rate_limited). ## List, change, delete - `GET /v1/leads/{id}/photos` — primary first, then oldest first, all on one page; each `url` works for one hour, so read the list again rather than storing URLs. - `PATCH /v1/leads/{id}/photos/{photo}` — `{"kind": "professional"}` or `{"is_primary": true}` (the previous primary photo stops being primary). Accepts `If-Match`. - `DELETE /v1/leads/{id}/photos/{photo}` — removes the file, then the photo, and answers `204` without a body. If it was her primary photo, the oldest remaining one becomes primary. If the file cannot be removed, nothing changes and you get [`502 upstream_failed`](https://docs.creator-guard.com/errors/#upstream_failed) — retry. ## When photos lock Once her listing is **live**, photos can no longer change: upload, change and delete answer [`409 photos_locked`](https://docs.creator-guard.com/errors/#photos_locked). Ask us if a photo must go. ## Consent `consent_status` follows her consent: `pending` until she grants it, `granted` afterwards, `revoked` if she withdraws it. --- # Account & earnings Source: https://docs.creator-guard.com/account/ ## Your profile `PATCH /v1/me` (scope `account:write`) changes `display_name`, `company_name`, `telegram_username` and `website` — the same fields and checks as the portal's profile page. Send only what changes. `null` or an empty string clears the company name or the website; the Telegram username takes `name`, `@name` or a `t.me/name` link and cannot be removed. Like every `PATCH` it accepts `If-Match` with the `ETag` you last received for your account; without it the last write wins. `PUT /v1/me/logo` takes `multipart/form-data` with one `file` (PNG, JPEG or WebP, at most 2 MB); we scale it to at most 512 px and remove every metadata block. `DELETE /v1/me/logo` removes it. Both answer with your account. Logos count against the same upload limit as [photos](https://docs.creator-guard.com/photos/#limits). ## Suggest fields from text `POST /v1/extract` (scope `extract`) reads a profile text, a chat or your notes — `{"text": "…"}`, 20 to 20,000 characters — and suggests lead and listing fields under their API names. **Nothing is stored**: not the text, not the answer — so an `Idempotency-Key` is ignored and a retry simply runs again. Review the suggestions, then send the lead yourself. It works before you have accepted the terms. Limits: **20 per minute and 200 per day** per account, halved in test mode. If the AI service fails we answer [`502 upstream_failed`](https://docs.creator-guard.com/errors/#upstream_failed); try again later. In [test mode](https://docs.creator-guard.com/test-mode/) the answer is a fixed fictitious example. ## Commissions A commission is booked for your lead when her placement completes. `GET /v1/commissions` (scope `earnings:read`) lists them, newest first, with the filters `status` (`due`, `paid`, `void`), `created_since` and `lead`; `GET /v1/commissions/{id}` reads one. `?expand=lead` returns a short lead object (`id`, `creator_name`, `creator_ref`, `stage`) in `lead` instead of its id. | Field | Meaning | |---|---| | `fee_total` | The placement fee the agency paid | | `creator_guard_amount` | Creator Guard's share | | `your_amount` | Your commission | | `status` | `due` (we owe it), `paid` (`paid_at` set) or `void` | Events: `commission.created`, `commission.paid`, `commission.voided` — see [Events](https://docs.creator-guard.com/events/). ## Payout details `GET /v1/payout-details` (scope `earnings:read`) shows the `method` (`bank`, `paypal` or `crypto`), a **masked** destination such as `DE89 •••• 3000` and when they were last changed; all three are `null` until you save payout details. The API never shows or changes the full details: change them in the portal (**Settings → Payout**), which asks for your second factor. --- # Idempotency & retries Source: https://docs.creator-guard.com/idempotency/ When a request times out you cannot tell whether it reached us. Retry it — with the same `Idempotency-Key`, so a second copy cannot act twice. ## `Idempotency-Key` Every `POST` accepts an `Idempotency-Key` header: any unique string of 1–255 printable ASCII characters, for example a UUID you generate per operation and **store with it**, so a retry sends the same value. Anything else → [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field). | Retry with the same key | Answer | |---|---| | Same request, first one finished | The **stored first answer** — same status, same body byte for byte, same `ETag` and `Location` — with `Idempotent-Replayed: true`. Nothing runs again. | | Same request, first one still running | [`409 idempotency_in_progress`](https://docs.creator-guard.com/errors/#idempotency_in_progress) — wait a second and retry. | | Different path or body | [`422 idempotency_key_reused`](https://docs.creator-guard.com/errors/#idempotency_key_reused). Use a new key for a new operation. | "Same request" means the same path and the same body bytes: send the stored body again rather than serialising it anew. Answers are kept for **24 hours** per API key: another key of the same account (a colleague's, or the new key after a roll) never gets your stored answer, and the same request sent with it runs anew. What the endpoint itself answers is stored, `2xx` and `4xx` alike, except `429`; `5xx` and `429` answers never are, so a retry after a `500` or a `429` runs again. A request refused before the endpoint runs — key, scope, rate limit, terms or a malformed body — stores nothing, so once you fix the cause the same key works. `PATCH` takes no key: sending the same change twice has the same result. ## `external_id` — idempotency that never expires `POST /v1/leads` also recognises your own reference: a second create with an `external_id` you already used returns that lead (`200`) unchanged, even days later and without an `Idempotency-Key`. Use both: the key for safe retries, `external_id` so an import that loses its keys still cannot create a creator twice. Duplicate rules by Instagram handle: [Leads](https://docs.creator-guard.com/leads/#duplicates). ## A retry loop 1. Generate the `Idempotency-Key` once per operation and keep it. 2. On a timeout, a network error, `409 idempotency_in_progress`, `429` or `5xx`: wait and retry with the **same** key and body. No `429` is stored, `429 duplicate_limit_reached` included, so after `Retry-After` the same key runs the request again. 3. Wait `Retry-After` seconds when the answer has that header, otherwise back off exponentially (1 s, 2 s, 4 s, … up to a minute). 4. Never retry other `4xx` answers unchanged: fix the request first. --- # Errors Source: https://docs.creator-guard.com/errors/ Every error, at every status, has the same JSON body: ```json { "error": { "type": "invalid_request", "code": "age_below_18", "message": "listing.age must be 18 or over.", "field": "listing.age", "details": [ { "field": "listing.age", "code": "age_below_18", "message": "listing.age must be 18 or over." } ], "doc_url": "https://docs.creator-guard.com/errors/#age_below_18", "request_id": "req_c7x2m4qk3vbn5h6tjd2wle4pza" } } ``` | Member | Meaning | |---|---| | `type` | `invalid_request` (400, 404, 405, 409, 410, 412, 413, 415, 422), `authentication` (401), `permission` (403), `rate_limit` (429), `api_error` (5xx). | | `code` | Stable and machine-readable. **Branch on this.** An unknown code: act on the HTTP status. | | `message` | For a developer reading a log. The wording may change; never parse it. | | `doc_url` | This page, at the code's row. | | `request_id` | Same as the `X-Request-Id` header. Quote it to [support](https://docs.creator-guard.com/support/). | | `field` | The request field of the (first) problem, when there is one. | | `details` | Every field problem of the request at once: `[{field, code, message}]`. | Some codes add one more member: | Member | With | |---|---| | `lead` (`{id, creator_ref}`) | `duplicate_own_lead`: your existing lead. | | `parameter` | `unknown_parameter` and `invalid_cursor`: the query parameter. | | `agreement_type` | `terms_not_accepted`: the terms to accept (`referrer_terms`, `agency_terms`, `warranty_terms`, `api_terms` or `api_dpa`). | | `scope` | `insufficient_scope`: the scope the key lacks. | | `blockers` | `not_ready_for_review`: what is still missing. | | `current_state` | `invalid_state`: the state that blocks the call (`current_version` instead on agreement accept). | | `current_version` | `consent_text_outdated`: the text version that is current now — show her that text and ask again. | | `limit` | `limit_reached`: the limit that is reached. | ## Order of checks Request id → key (`401`, `403 account_not_active`) → test helpers with a live key (`404`) → IP allowlist → account type → scope → concurrency → rate limit → extract and upload limits → terms on writes → body (`413`, `415`, `400`) → `If-Match` → `Idempotency-Key` → the rules of the endpoint. Only the first failing check answers, except field validation, which reports every field in `details`. ## All codes The creator endpoints (`/v1/creator/…`, [Creator API](https://docs.creator-guard.com/creator-api/)) answer with the same codes; `invalid_token` and `expired_token` are theirs. The OAuth endpoints on `app.creator-guard.com` answer in the OAuth format instead ([OAuth errors](https://docs.creator-guard.com/oauth/#errors-of-the-oauth-endpoints)). | Status | Code | When | Retry | |---|---|---|---| | 400 | `invalid_json` | The body is not valid JSON. | no | | 400 | `invalid_body` | The body is not a JSON object (for example an array). | no | | 400 | `unknown_field` | A request field is not in the contract; `error.field` names it. | no | | 400 | `unknown_parameter` | A query parameter this endpoint does not support; `error.parameter` names it. | no | | 400 | `missing_field` | A required field is missing; `error.details` lists every problem. | no | | 400 | `invalid_field` | A value has the wrong type, length, range or format. | no | | 400 | `missing_contact` | `PATCH /v1/creator/profile` would leave her lead with neither `instagram_handle` nor `other_contact`. | no | | 400 | `age_below_18` | `age` is below 18. | no | | 400 | `consent_required` | `consent_confirmed` is not exactly `true`. | no | | 400 | `invalid_cursor` | `starting_after` or `ending_before` is not one of your leads; `error.parameter` names it. | no | | 401 | `missing_key` | No `Authorization: Bearer` header. | no | | 401 | `invalid_key` | The key is unknown or revoked. | no | | 401 | `expired_key` | The key is past its expiry date. | no | | 401 | `invalid_token` | The creator access token is unknown, revoked, or from the other mode (her grant ended or was revoked: send her through the authorize flow again). | refresh | | 401 | `expired_token` | The creator access token is past its hour: refresh it at `/oauth/token`. | refresh | | 403 | `account_not_active` | The account is pending approval or disabled. With a creator access token: the account that owns the OAuth app (her grant stays and works again once the account is approved). | no | | 403 | `terms_not_accepted` | A write needs the account's terms — and with a live key the API Terms (`api_terms`) and the data protection addendum (`api_dpa`); `error.agreement_type` names one at a time (the API Terms first), so accept and retry until the write goes through. | after accepting | | 403 | `insufficient_scope` | The key lacks the scope in `error.scope`. | no | | 403 | `wrong_account_type` | The endpoint is not for this account type. | no | | 403 | `ip_not_allowed` | The key has an IP allowlist that does not contain the caller. | no | | 403 | `mfa_required` | Portal only: key, webhook and payout changes need a second factor. API keys never get it. | after sign-in | | 403 | `referrer_app_not_allowed` | Creator token of an OAuth app owned by the account that referred her: her consent, 18+ confirmation and creator terms are given only on Creator Guard (consent link or creator portal). Withdrawing consent is never refused. | no | | 404 | `not_found` | Unknown path or id, or a resource of another account. | no | | 405 | `method_not_allowed` | The path exists, the HTTP method does not. | no | | 409 | `duplicate_own_lead` | Your lead with this Instagram handle is past `draft`; `error.lead` names it. | no | | 409 | `duplicate_other_referrer` | Another account already submitted this Instagram handle (create, or a `PATCH` of `instagram_handle`). | no | | 409 | `lead_locked` | Lead fields can no longer change (the lead left `draft`). | no | | 409 | `listing_locked` | The listing is live; its fields and fee can no longer change. | no | | 409 | `photos_locked` | The listing is live; its photos can no longer change (partner and creator endpoints alike). | no | | 409 | `invalid_state` | Not allowed in the current state; `error.current_state` names it (`error.current_version` on agreement accept). | no | | 409 | `offer_taken` | Accepting an offer: another agency accepted her first. | no | | 409 | `offer_expired` | Accepting or declining an offer whose deadline passed. | no | | 409 | `listing_unavailable` | Accepting an offer whose listing was pulled or that we retracted. | no | | 409 | `payment_pending` | The step needs a paid reservation (offer progress, the creator's contact, a warranty claim). | later | | 409 | `deal_paid` | Marking an offer lost after the placement fee was received. A paid deal ends only through a warranty claim or Creator Guard. | no | | 409 | `undo_window_passed` | Undoing an accept after `undo_until`. | no | | 409 | `claim_exists` | A second warranty claim on the same reservation. | no | | 409 | `warranty_expired` | A warranty claim after the warranty ended. | no | | 409 | `external_id_taken` | `external_id` is used by another of your leads. | no | | 409 | `consent_text_outdated` | Granting consent, the 18+ confirmation or accepting the creator terms with a text version that is not the current one; `error.current_version` names it. Show her the current text (`GET /v1/creator/consent-text`) and ask again. A withdrawal never fails for this reason. | after refetch | | 409 | `idempotency_in_progress` | The first request with this `Idempotency-Key` is still running. | yes | | 409 | `limit_reached` | A limit of the account is reached (10 active keys or 10 webhook endpoints per mode, 20 photos per lead, 1,000 open deliveries per endpoint on replay); `error.limit` is the number. | no | | 410 | `version_sunset` | A retired major version (not used in v1 yet). | no | | 412 | `precondition_failed` | `If-Match` is not the current `ETag`. | after refetch | | 413 | `payload_too_large` | The body is larger than 1 MB. | no | | 415 | `unsupported_media_type` | The body is not `application/json`. | no | | 422 | `not_ready_for_review` | Blockers remain; `error.blockers` lists them. | after fixing | | 422 | `idempotency_key_reused` | The same `Idempotency-Key` with a different body. | no | | 422 | `image_unreadable` | The uploaded file is not a readable JPEG, PNG or WebP image. | no | | 429 | `rate_limited` | A rate limit is used up; wait `Retry-After` seconds. | yes | | 429 | `concurrency_limited` | More than 25 requests of this key are in flight. | yes, slower | | 429 | `duplicate_limit_reached` | The daily budget of answers about other accounts' creators is used up. | after Retry-After | | 500 | `internal_error` | Unexpected error on our side; quote `request_id`. | yes | | 502 | `upstream_failed` | A service we depend on failed (text extraction, or the DNS lookup of a webhook URL); nothing was stored. | yes | | 503 | `not_configured` | A setting is missing on our side (for example text extraction), or test mode is briefly unavailable. | no | ## 5xx and gateway errors `500 internal_error` never contains database details. Retry with the same `Idempotency-Key`: a `5xx` answer is never stored, so the retry runs again. A `502` or `504` without a JSON body comes from the gateway during a restart; retry after a few seconds. --- # Rate limits Source: https://docs.creator-guard.com/rate-limits/ | Limit | Default | Applies to | |---|---|---| | Requests | **100 per minute** and **10,000 per day** | each key, sliding windows | | Requests in flight at once | **25** | each key, per server instance | | Uploads (photos, logo) in flight at once | **1** | each key, per server instance | | Webhook replays | **10 per day** | the whole account, per mode | | Answers about other accounts' creators | **20 per rolling 24 hours** | the whole account | Defaults can be raised per account — [talk to us](https://docs.creator-guard.com/support/) before a large import. `GET /v1/me` shows the limits in effect for your account (`limits.per_minute`, `limits.per_day`, `limits.duplicate_budget`). ## What counts - Every request with a valid key counts, whatever its result — also `400`, `403`, `409` and `500`. - `429` answers, `401` answers and requests refused for [`ip_not_allowed`](https://docs.creator-guard.com/errors/#ip_not_allowed) do not count against the key (`401`s use the [per-IP budget](#requests-without-a-valid-key) instead). - Windows are sliding: they look back 60 seconds and 24 hours from each request and never reset at a fixed time. ## Headers Every answer that got past the key, IP, scope and concurrency checks tells you where you stand: ```http RateLimit-Policy: 100;w=60, 10000;w=86400 RateLimit: limit=100, remaining=97, reset=42 ``` `RateLimit` describes the tighter of the two windows: the one that is used up, otherwise the one with fewer requests left. `remaining` already counts the current request; `reset` is the number of seconds until a slot in that window frees up. Slow down as `remaining` approaches 0 instead of waiting for a `429`. ## When you hit a limit ```http HTTP/1.1 429 Too Many Requests Retry-After: 42 ``` The body is an [error](https://docs.creator-guard.com/errors/) with `code` [`rate_limited`](https://docs.creator-guard.com/errors/#rate_limited). `Retry-After` is the `reset` of the window that is used up (the daily one when both are). Pause the **whole queue** for that long, not just the one request. ## Requests without a valid key Requests that have no valid key — no `Authorization` header, an unknown, revoked or expired key — as well as `GET /v1/` and paths that do not exist, share a separate budget **per client IP address: 30 per minute**, refilled continuously (one every 2 seconds). Past it, every such request from that address gets [`429 rate_limited`](https://docs.creator-guard.com/errors/#rate_limited) with `Retry-After`, without `RateLimit` headers. Requests with a valid key never use this budget, and a key that was accepted in the last 10 minutes is let through even from an address whose budget is used up; a key never seen before (or not for 10 minutes) from such an address waits like any other request until the budget refills. Like the concurrency limit it is kept per server instance. A correctly configured integration never comes near it; a loop retrying a wrong key does. ## Concurrency More than 25 requests of one key in flight at the same moment → [`429 concurrency_limited`](https://docs.creator-guard.com/errors/#concurrency_limited) with `Retry-After: 1`. Run at most about 10 requests in parallel and the limit never bites. The limit is kept per server instance; during a release two instances can briefly answer, so do not rely on reaching exactly 25. Uploads (`POST /v1/leads/{id}/photos`, `PUT /v1/me/logo`) are tighter: **one upload per key at a time**. A second upload of the same key while the first is still running → `429 concurrency_limited` with `Retry-After: 1`, before its body is read. Each server instance also takes only a few uploads of all accounts at once; when they are busy, an upload waits up to 10 seconds before it starts, and past that (or when too many are already waiting) it gets `429 concurrency_limited` with `Retry-After: 2`. Upload photos one after the other. ## Duplicate budget A [`409 duplicate_other_referrer`](https://docs.creator-guard.com/errors/#duplicate_other_referrer) tells you another account already submitted a creator. So that this cannot be used to test lists of handles against other accounts' creators, the account gets **20 such answers per rolling 24 hours**, counted across all of its keys at the moment we answer, so parallel requests cannot exceed it. When they are used up, **every request that has to check a handle** — `POST /v1/leads` with an `instagram_handle`, or a `PATCH /v1/leads/{id}` that changes it — answers [`429 duplicate_limit_reached`](https://docs.creator-guard.com/errors/#duplicate_limit_reached), whether that creator is new or taken, so it reveals nothing. `Retry-After` says when the oldest counted answer leaves the window. Requests that check no handle are not affected, and neither is a `POST` whose `external_id` you already used: it returns that lead before any handle check. ## Sending many creators There is no batch endpoint: one request per creator, with an `Idempotency-Key` and `external_id` each. A steady pace of one request per second stays far below the limits; up to 10 in parallel is fine. For more than 10,000 a day, [talk to us](https://docs.creator-guard.com/support/) first. --- # Pagination & sync Source: https://docs.creator-guard.com/pagination/ Lists such as `GET /v1/leads` return one page: ```json { "object": "list", "data": [ { "object": "lead", "id": "lead_hz5ikyc3pnhkrhlb6p7elkx2qy" } ], "has_more": true, "next_cursor": "lead_hz5ikyc3pnhkrhlb6p7elkx2qy" } ``` | Parameter | Meaning | |---|---| | `limit` | 1–100 items per page, default 25. | | `starting_after` | An id from the previous page (use `next_cursor`): the next, older page. | | `ending_before` | The first id of the current page: the newer page before it. | Order is always newest first (`created_at`, then `id`), so pages stay stable while new leads arrive. `next_cursor` is the id to send as `starting_after` for the next, older page; it is `null` on the last page. With `ending_before`, `has_more` says whether there are still newer leads; to go further back, send the first id of that page as `ending_before` again. - An id that is not one of your leads → [`400 invalid_cursor`](https://docs.creator-guard.com/errors/#invalid_cursor), with the parameter's name in `error.parameter`. - `starting_after` and `ending_before` together, a `limit` outside 1–100, or the same parameter twice → [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field). ## Filters `GET /v1/leads` takes these filters; they combine with AND. Any other parameter → [`400 unknown_parameter`](https://docs.creator-guard.com/errors/#unknown_parameter), with its name in `error.parameter`. An invalid filter value → [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field). | Filter | Example | Matches | |---|---|---| | `stage` | `stage=draft` | One [stage](https://docs.creator-guard.com/lead-lifecycle/). | | `external_id` | `external_id=crm-000042` | Your reference, exactly. | | `creator_ref` | `creator_ref=CR-1047` | Her creator number (`1047` works too). | | `instagram_handle` | `instagram_handle=miacreates` | Normalised like on create, so `@MiaCreates` or a profile link find her too. | | `q` | `q=mia` | Part of her name, ignoring case. | | `created_since`, `updated_since` | `updated_since=2026-10-09T08:00:00Z` | RFC 3339 timestamps, inclusive. | | `has_blockers` | `has_blockers=true` | Leads that still have (or, with `false`, have no) [blockers](https://docs.creator-guard.com/lead-lifecycle/#next-actions). | ## Keeping in sync Every lead has `updated_at`, the last change to the lead or her listing. Remember the time of your last sync and ask for `GET /v1/leads?updated_since=`, following `next_cursor` with `starting_after` until `has_more` is `false`. Take the new sync time from **before** the first request, so a change during the sync is picked up next time. A few stage changes can happen without a change to `updated_at` (an offer simply running out, for example), so re-read leads that are still in progress once a day as well. Or let us tell you: [webhooks](https://docs.creator-guard.com/webhooks/) deliver every change within seconds, and `GET /v1/events` keeps them for 30 days. --- # Usage, logs & audit Source: https://docs.creator-guard.com/usage/ Three read-only views of what your integration did — the usage chart under **Settings → API** in the portal shows the same numbers. ## Request log `GET /v1/request-logs` (scope `account:read`): every request of the last **30 days** in the mode of your key, newest first, with `method`, the route template (`/v1/leads/{id}`), `status`, `error_code`, the `key` that made it and `duration_ms`. Filters: `status`, `route`, `key`, `created_since`; pages with `limit`, `starting_after` and `ending_before`. Requests refused before any work for a limit — `429 rate_limited` and `429 concurrency_limited` — are not logged and not counted in usage; they never counted towards the rate limit either. A request refused with `403 ip_not_allowed` **is** logged and shows in usage, so you can see when one of your keys is used from an address outside its allow-list; it does not count against the rate limit. The log never holds request or response bodies, headers or creator data. The `id` (`req_…`) is the `X-Request-Id` of that request — quote it to [support](https://docs.creator-guard.com/support/). ## Usage `GET /v1/usage?from=2026-10-01&to=2026-10-30` (scope `usage:read`) counts the requests of your account in the mode of your key, per UTC day (`series`), per route (`by_route`) and per key (`by_key`): | Field | Meaning | |---|---| | `requests` | All requests, every status | | `errors` | Answers with status 400 or higher; `series[].error_codes` counts them by `code` | | `p50_ms`, `p95_ms` | Median and 95th percentile of the duration on our side; `null` without requests | `from` and `to` are dates (UTC), both included, at most 90 days apart. Both are optional: without them you get the last 30 days up to today. `granularity` is `day`. ## Audit trail `GET /v1/audit-events` (scope `audit:read`): changes to your account in the last **90 days** in the mode of your key, newest first (a live key also sees the changes that concern the whole account, such as your key policy or limits; a test key only test-mode changes) — who (`actor.kind`: `key`, `user`, `admin` or `system`), what (`action`), on what (`target`), from which IP and browser or client, and the changed names and values in `details`. Filters: `action`, `created_since`; pages with `limit`, `starting_after` and `ending_before`. | `action` | When | |---|---| | `api_key.created`, `api_key.rolled`, `api_key.revoked` | A key changed (a revocation by your key policy has actor `system`; keys revoked because their member was removed or got a narrower role name the reason and the member in `details`) | | `api_key.leaked` | A key turned up in public (for example GitHub secret scanning reported it) and we revoked it at once; actor `system` | | `key_policy.changed` | Maximum key age or auto-revocation changed | | `webhook_endpoint.created`, `.updated`, `.deleted`, `.secret_rotated` | A webhook endpoint was created, changed, deleted or got a new secret | | `webhook_endpoint.tested`, `.replayed`, `.delivery_retried` | A test send, a replay or a retry was started with the API | | `oauth_app.created`, `.updated`, `.deleted`, `.secret_rolled` | An [OAuth app](https://docs.creator-guard.com/oauth/) was registered, changed, deleted or got a new client secret (a secret replaced because a member was removed or got a narrower role has actor `system`) | | `oauth_app.secret_leaked`, `oauth_app.token_leaked` | A client secret or a creator's access or refresh token of the app turned up in public (for example GitHub secret scanning) and we replaced the secret (`details.secret`: `current`, or `previous` — then your current secret keeps working) or ended that creator's authorization at once (`details.grant`); actor `system` — see [OAuth](https://docs.creator-guard.com/oauth/) | | `agreement.accepted` | Terms were accepted through the API | | `member.invited`, `member.invitation_revoked` | An invitation was sent or revoked — see [Members & roles](https://docs.creator-guard.com/members/) | | `member.joined`, `member.role_changed`, `member.removed` | Someone accepted an invitation, got another role or was removed | | `member.login_email_changed` | A member (not the owner) changed the email address of their own login in the portal; the entry names the member and carries no address | | `account.updated`, `account.logo_updated`, `account.logo_removed` | Your profile or logo changed with the API | | `sandbox.reset` | The test data was deleted with `POST /v1/test-helpers/reset` | | `limits.changed` | Creator Guard changed your limits | | `lead.created_by_admin` | Our team added a creator to your account for you; she is yours like any lead you submit (the `lead.created` webhook fires as usual) | | `account.mfa_enabled`, `account.mfa_removed` | An authenticator (second factor) was set up or removed — also listed in the portal under **Settings → Login & security**. We send no email about it. | New actions may be added. `details` never contains a secret or creator data. ## Retention | Data | Kept | |---|---| | Request log | 30 days readable (90 days on our side) | | Usage | Up to 90 days back | | Audit trail | 90 days | | Events and webhook deliveries | 30 days | --- # Agencies: offers and reservations Source: https://docs.creator-guard.com/agencies/ Everything an agency does in the agency portal also works through the API: keep your search profile current, act on the creators we offer you, pay for the ones you accept and follow up with them. Your key is an **agency key**. It reaches the agency endpoints below and the referral endpoints (`/v1/leads…`) for creators you refer yourself. The agency endpoints answer only agency keys. A referral partner's key gets [`403 wrong_account_type`](https://docs.creator-guard.com/errors/#wrong_account_type) — before the scope is checked, so a referrer key on `GET /v1/offers` sees `wrong_account_type`, not `insufficient_scope`. Agency keys issued by Creator Guard carry `account:read`, `account:write`, `agreements:write`, `earnings:read`, `leads:read`, `leads:write`, `offers:read`, `offers:write`, `reservations:read`, `reservations:write` and `search_profile:write`. What each scope allows: [API keys](https://docs.creator-guard.com/api-keys/#scopes). Writes need the current **agency terms** ([`403 terms_not_accepted`](https://docs.creator-guard.com/errors/#terms_not_accepted) with `error.agreement_type`). Check and accept them with `GET /v1/agreements` and `POST /v1/agreements/agency_terms/accept`. Reads never need terms. ## Search profile and agency profile `GET /v1/search-profile` returns what we match creators against. `PUT /v1/search-profile` **replaces it**: every field you leave out goes back to its default. Read it, change what you need, send the whole object back (with its `ETag` in `If-Match` if two systems may write). `flex` says where a creator may be near your criteria instead of matching exactly. A key that is present means "may deviate", a missing key means "must match". Only the portal's levels are accepted: | Key | Levels | |---|---| | `age` | `3`, `8`, `20` (years outside your range) | | `revenue` | `"zero"` (no revenue yet is fine), `50`, `100` (percent outside your range) | | `english` | `3`, `5` (levels below your minimum), `"any"` | | `fee` | `25`, `50`, `100` (percent above your maximum fee) | | `split` | `10`, `20`, `30` (points above your maximum creator share) | | `stage` | `"opposite"` (the other creator stage is fine) | | `niches`, `platforms`, `content_types`, `languages` | `{"also": [...]}`: other values that are fine; `[]` = anything else is close | Any other level is [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field) with `field` set to `flex.`. Money fields are US dollars only (`currency: "USD"`); `revenue_min` and `revenue_max` are whole dollars. `max_placement_fee` is compared with a listing's fee as it is, without currency conversion. `PATCH /v1/agency-profile` changes only the fields you send. `tier`, `verified_revenue` and `vetting` are set by Creator Guard; sending them is [`400 unknown_field`](https://docs.creator-guard.com/errors/#unknown_field). ## Offers When we match a creator to you, you get an offer (`offer.created`). Offers with a creator's profile reach your account only after your agency passed our vetting; GET /v1/agency-profile shows the state (`vetting.status` is `registered`, `in_review` or `vetted`, and `vetting.waiting_matches` counts the creators matched to you who wait for it). In the sandbox `vetting.status` is always `vetted`. An offer moves like this: | Status | Meaning | What you can do | |---|---|---| | `offered` | Open until `expires_at` | `accept`, `decline` (with a `note` of 50–500 characters) | | `accepted` | Reserved for you; pay the reservation | `undo-accept` until `undo_until` while unpaid; `mark-contacted` or `mark-signed` once paid; `mark-lost` only while unpaid | | `contacted` | You reached her | `mark-in-talks`, `mark-signed` | | `in_talks` | You are negotiating | `mark-signed` | | `signed` | She signed with you | — | | `lost` | It did not work out (`outcome_reason`) | — | | `declined`, `expired`, `retracted` | Closed: you declined, the deadline passed, or we withdrew the offer | — | A deal you paid for cannot be marked lost (`409 deal_paid`): if she does not work out, file a warranty claim on the reservation instead. Only a warranty claim or Creator Guard ends a paid deal. Every offer carries `next_actions`, so you never have to re-implement these rules. An open offer whose deadline passed reads `expired` at once, even before our hourly job closes it. `GET /v1/offers` filters by `status`, `created_since`, `updated_since` and `expires_before`; `PATCH /v1/offers/{id}` keeps your own `agency_note`. **Accepting.** `POST /v1/offers/{id}/accept` needs the current agency terms **and the current warranty terms**. Without them the answer is `403 terms_not_accepted` with `error.agreement_type: "warranty_terms"` and nothing changes: read the version in `GET /v1/agreements` and accept it with `POST /v1/agreements/warranty_terms/accept`. Only one agency can win a creator: if another agency accepted her first, you get [`409 offer_taken`](https://docs.creator-guard.com/errors/#offer_taken). A passed deadline is [`409 offer_expired`](https://docs.creator-guard.com/errors/#offer_expired), a withdrawn listing [`409 listing_unavailable`](https://docs.creator-guard.com/errors/#listing_unavailable). The accept creates a reservation (`reservation` on the offer) in `awaiting_payment`. **Undo.** For a few minutes after accepting (`undo_until`; the length is `accept_undo_minutes` in `GET /v1/settings`) and before any payment, `POST /v1/offers/{id}/undo-accept` puts the offer back to `offered` and cancels the reservation. Later: [`409 undo_window_passed`](https://docs.creator-guard.com/errors/#undo_window_passed). ## Reservations | Status | Meaning | |---|---| | `awaiting_payment` | Transfer `amount` with `payment_reference` before `payment_due_at` | | `paid` | We received the fee. The creator's contact is unlocked; the warranty runs until `warranty_until` | | `completed` | The warranty ended without a refund | | `refunded` | We refunded you after an accepted warranty claim | | `cancelled` | Not paid in time, or you undid the accept | `mark-contacted` and `mark-signed` need a paid reservation ([`409 payment_pending`](https://docs.creator-guard.com/errors/#payment_pending) before). `GET /v1/reservations/{id}/creator` returns her name, Instagram, other contact, platforms, followers, niche and creator number once the reservation is `paid` or `completed`; before payment it is `409 payment_pending`. **Warranty claim.** While the reservation is paid and the warranty runs, file **one** claim: `POST /v1/reservations/{id}/warranty-claim` with `reason` (`creator_unreachable`, `no_show`, `false_data`, `contract_refused`, `other`) and an optional `note` (up to 2,000 characters). A second claim is [`409 claim_exists`](https://docs.creator-guard.com/errors/#claim_exists); after the warranty it is [`409 warranty_expired`](https://docs.creator-guard.com/errors/#warranty_expired). The claim shows in `warranty_claim` with its `filed_at`. Only your own claim counts: a refund Creator Guard decides on its own (and the sandbox refund helper) keeps `warranty_claim` at `null` and sends no `warranty_claim.created`. ## What you see, and when | | Open offer | After payment | |---|---|---| | Creator number (`CR-…`) | ✓ | ✓ | | Creator name (`creator_name`; `null` before payment) | — | ✓ | | Listing: age, country, languages, content, availability, deal terms, placement fee | ✓ | ✓ | | Photos she agreed to share (signed links, 1 hour) | ✓ | ✓ | | Instagram, other contact, platforms, followers, niche | — | ✓ | | Who referred her, internal notes, her consent records | never | never | Once an offer is declined, expired, retracted or lost, its listing and photos are no longer shown (`listing: null`; photos answer `409 invalid_state`) — unless you paid for her: after payment they stay visible. "After payment" means a reservation of yours for her that is `paid` or `completed`; after a refund her name is `null` again. **She withdraws her consent.** Then her listing goes offline for every agency: `listing` and `photo_count` are `null` and her photos answer `409 invalid_state` on every offer, whatever its status — except for the agency whose placement of her is `completed`, which keeps the listing (her photos stay hidden). An open offer is also retracted, and so is an accepted offer whose reservation still awaits payment: that reservation is cancelled (`offer.retracted`, `reservation.cancelled`), and no reservation of hers can be paid while her withdrawal stands. A paid reservation is not touched. Every agency holding an offer for her receives `offer.consent_revoked`: delete what you stored of her listing and photos. If she gives her consent again, the normal rules apply again. Her contact after payment (`GET /v1/reservations/{id}/creator`) is not affected. ## Events `offer.created`, `offer.accepted`, `offer.declined`, `offer.expired`, `offer.retracted`, `offer.reopened` (your retracted offer is open again because the agency that won her undid its accept), `offer.progressed` (contacted, in talks, signed, lost, or back to offered after your own undo; `previous_attributes.status` has the old status), `offer.consent_revoked` (she withdrew her consent — every agency holding an offer for her, any status), `reservation.created`, `reservation.paid`, `reservation.completed`, `reservation.refunded`, `reservation.cancelled` and `warranty_claim.created`. They go only to your agency, and they fire the same way whether you act in the portal or through the API. Reading them needs `offers:read` (offer events) or `reservations:read` (reservation events) — see [Events](https://docs.creator-guard.com/events/) and [Webhooks](https://docs.creator-guard.com/webhooks/). ## Testing with a test key With a `cg_test_` key everything happens in the sandbox ([Test mode](https://docs.creator-guard.com/test-mode/)): | Request | Plays | Result | |---|---|---| | `POST /v1/test-helpers/offers` | Our matching | A synthetic creator offered to you (optional `creator_name` — shown after `mark-paid` — `placement_fee`, `expires_in_hours`) | | `POST /v1/test-helpers/reservations/{id}/mark-paid` | Our bookkeeping | `awaiting_payment` → `paid` | | `POST /v1/test-helpers/reservations/{id}/complete` | The end of the warranty | `paid` → `completed` | | `POST /v1/test-helpers/reservations/{id}/refund` | An accepted warranty claim | `paid` → `refunded` | | `POST /v1/test-helpers/clock/advance` | Time passing, `{"hours": n}` (1–720) | Offers expire, unpaid reservations are cancelled, warranties complete | A live key gets `404 not_found` on every test helper. **Known limit:** `POST /v1/test-helpers/reset` empties the sandbox of your referral data, but your test offers and reservations as an agency stay in place; let them expire with `clock/advance` or ignore them. Error codes: [Errors](https://docs.creator-guard.com/errors/); every field: [API reference](https://docs.creator-guard.com/reference/); what changed: [Changelog](https://docs.creator-guard.com/changelog/). --- # Members & roles Source: https://docs.creator-guard.com/members/ An account can have several people. Each signs in with their own email address and password and has one role. API keys, webhooks and OAuth apps belong to the account, never to a person, so nothing stops working when someone leaves. ## Roles | What the person can do | Owner | Admin | Developer | Viewer | |---|---|---|---|---| | Read everything of the account: leads, offers, earnings, settings | ✓ | ✓ | ✓ | ✓ | | Change leads, listings, photos, offers, reservations, the search profile, the profile and logo; accept terms | ✓ | ✓ | – | – | | API keys, webhooks, OAuth apps, request logs, usage, audit log | ✓ | ✓ | ✓¹ | – | | Invite people, change roles, remove people | ✓ | ✓ | – | – | | See and change payout details | ✓ | – | – | – | | Leave the account | – | ✓ | ✓ | ✓ | ¹ A developer creates, rolls and revokes only keys with read scopes plus `keys:manage`, `webhooks:manage`, `usage:read` and `audit:read` — never a key that writes, manages members or OAuth apps, or reads earnings. The key policy (maximum key age, revoking unused keys) is for owners and admins. The **owner** is the login the account was created with. There is exactly one. Nobody can remove or demote the owner, and the owner cannot leave. An admin manages everyone else, including other admins; nobody changes their own role. ## How someone joins 1. An owner or admin invites an email address with a role: in the portal (Settings → Members) or with `POST /v1/members`. 2. Creator Guard shows a join link `https://app.creator-guard.com/join/…` **once**. It is valid for 48 hours. Send it to the person yourself — Creator Guard sends no email. **Whoever opens the link first sets the password for this address**, so send it only through a channel the person controls. 3. The person opens the link. Without a Creator Guard login yet, they choose a password for **exactly that email address** on the join page and the login is created; with an existing login for that address, they sign in and accept. From then on they work in the account with their role. A link works once and stops working when it is accepted, revoked or expired. A login belongs to one account only: the owner or a member of another account, a creator login and Creator Guard staff cannot join. Inviting such an address looks exactly like any other invitation — in the portal and over the API (`201` with a `join_url`), listed and revocable like the others, and its join page looks the same — but it can never be accepted. So an invitation tells you nothing about what kind of login an address has. If someone reports that they cannot accept a new link although they signed in with the invited address, they probably already belong to another account. Inviting the same address again creates a new link and retires the old one, in the portal and over the API. An account can send at most 20 invitations in 24 hours; every invitation counts, including those whose link cannot be used. A login created on the join page is shown as **unverified** ("login created via invitation link — email not verified", `email_verified: false` in the API): the person proved only that they had the link. When such a person is removed or leaves and belongs to no other account, their login is deleted, so the address is free for its owner again. Member changes in the portal need two-factor authentication. An API key with `members:manage` acts for the account and needs none — treat it like a password. Over the API you invite developers and viewers; admins are invited in the portal. ## With the API All three operations need the scope `members:manage` and a live key. A `cg_test_` key gets `404 not_found` ("Members are managed in live mode."), because test mode has no logins. Member management works before the terms are accepted. List the people and open invitations (owner first, not paginated): ```bash curl https://api.creator-guard.com/v1/members \ -H "Authorization: Bearer $CG_KEY" ``` Invite someone: ```bash curl -X POST https://api.creator-guard.com/v1/members \ -H "Authorization: Bearer $CG_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"email": "dev@example.com", "role": "developer"}' ``` The answer is the invitation with `join_url`. Pass the link on and do not store it: it is not shown again — a retry with the same `Idempotency-Key` within 24 hours returns the same invitation with `join_url: null`. Lost the link? Delete the invitation and invite again. ```json { "object": "member", "id": "inv_eaaaaaaaabaabaaaaaaaaaaaae", "email": "dev@example.com", "role": "developer", "status": "invited", "created_at": "2026-10-13T09:00:00Z", "email_verified": null, "expires_at": "2026-10-15T09:00:00Z", "join_url": "https://app.creator-guard.com/join/7c4e…" } ``` Remove a person (`mem_…`) or revoke an invitation (`inv_…`): ```bash curl -X DELETE https://api.creator-guard.com/v1/members/inv_eaaaaaaaabaabaaaaaaaaaaaae \ -H "Authorization: Bearer $CG_KEY" ``` ## When someone leaves Removing a person (portal or API), their leaving, and lowering their role all happen in one step with what they could still use: - their open invitations are revoked (also when an admin becomes developer or viewer); - every API key whose secret they had — keys they created or rolled in the portal, and keys those keys created over the API — is revoked (`revoked_reason: member:removed`); after a downgrade only the keys above the new role (`member:role_changed`); - webhook endpoints whose current signing secret they know (removal, or a downgrade to viewer) get a new secret that nobody has seen and are disabled. Roll the secret in the portal, put the new one into your receiver and enable the endpoint again — until then your receiver should reject anything signed with the old secret. Their login then acts for no account from its next request on. Deleting the owner answers `409 invalid_state` with `current_state: owner`. Roles are changed in the portal; the API invites and removes. Every change is recorded in the audit log (`GET /v1/audit-events`): `member.invited`, `member.joined`, `member.role_changed`, `member.removed`, `member.invitation_revoked`, `member.login_email_changed` (a member changed the email address of their own login; no address in the entry, the owner's own change is not listed). --- # Lead lifecycle Source: https://docs.creator-guard.com/lead-lifecycle/ Every lead has one `stage`, computed by Creator Guard: | `stage` | Meaning | You can | |---|---|---| | `draft` | Submitted; listing, photos and her confirmations are being completed. Every new lead starts here. | edit lead and listing, set the fee, withdraw, submit for review | | `in_review` | Creator Guard reviews the profile. | edit the listing and the fee, withdraw | | `ready` | Approved; we match her with agencies. | withdraw, until an agency offer is open | | `offered` | Offered to one or more agencies. | read | | `accepted` | An agency accepted her; the placement fee is due. | read | | `in_placement` | Fee received; the agency is onboarding her. | read | | `placed` | Signed with an agency. | read | | `rejected` | Not a fit; `outcome_reason` says why. | read | | `lost` | The placement did not work out (an agency reports it only before payment; after payment Creator Guard decides). | read | | `withdrawn` | Withdrawn by you. | read | New stages may be added; treat an unknown one as "in progress". `external_id` can be changed at every stage. ## `next_actions` Do not re-implement these rules — every lead tells you what is possible right now: ```json { "can_edit_lead": true, "can_edit_listing": true, "can_edit_fee": true, "can_withdraw": true, "can_submit_for_review": false, "blockers": ["photos_missing", "consent_missing"] } ``` `blockers` lists what keeps her off the marketplace while she is a draft or in review; how to clear each one: [Listing & review](https://docs.creator-guard.com/listing/#submit-for-review). Every blocker, `fee_missing` included, stops you from submitting her for review. `GET /v1/leads?has_blockers=true` finds every lead that still needs something. ## Edit windows | What | Until | |---|---| | Lead fields | you submit her for review (then [`409 lead_locked`](https://docs.creator-guard.com/errors/#lead_locked)); `external_id` at any stage | | Listing fields | her listing goes live at `ready` (then [`409 listing_locked`](https://docs.creator-guard.com/errors/#listing_locked)) | | Fee | the end of review; house accounts never set a fee ([`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field)) | | Withdraw | an agency offer is open or under way, or she is closed (then [`409 invalid_state`](https://docs.creator-guard.com/errors/#invalid_state)) | ## After review Creator Guard approves her (`ready`) or rejects her with a reason. Approved creators are offered to agencies whose search profile fits; agencies see her without contact details, and only the agency that accepts her and pays the placement fee gets them. You see the milestones in [`GET /v1/leads/{id}/timeline`](https://docs.creator-guard.com/reference/#op-getTimeline) and your money in [`GET /v1/leads/{id}/earnings`](https://docs.creator-guard.com/reference/#op-getEarnings) — never agency names. If she withdraws her consent, her listing is taken off the marketplace and she is no longer offered to agencies. ## Matching her back to your system | In the API | In the portal | |---|---| | `id` (`lead_…`) | Her lead. | | `creator_ref` (`CR-1047`) | Her creator number, shown with her everywhere. | | `external_id` | "Your ref" in **My Creators**. | --- # Data protection & consent Source: https://docs.creator-guard.com/data-protection/ You are sending us personal data about real people. This page explains what you declare, what the creator confirms herself, and what we keep. ## What `consent_confirmed: true` means `consent_confirmed` must be exactly `true`, otherwise [`400 consent_required`](https://docs.creator-guard.com/errors/#consent_required). With it **you declare that the creator agreed** to be referred to management agencies through Creator Guard **and to you sending us her details** — including her age and content types, which can reveal information about her sex life and are special-category data under the GDPR. > **Important:** > > Never send `true` for someone who has not agreed. A creator who does not know about the referral does not answer her consent link, and she is never offered to anyone. ## She confirms herself Your declaration lets us create the lead. It is **not** enough to offer her to agencies: she confirms that she is **18 or older** and gives her **consent** herself, through her personal [consent link](https://docs.creator-guard.com/listing/#her-confirmations) or the creator portal. Only she may confirm — never open her link and confirm for her. When and from where she confirmed is recorded; through the API you see only the status and the dates, never her IP address or browser. She can withdraw her consent at any time; her listing then leaves the marketplace and she is no longer offered to agencies. ## Who sees what | Who | What | |---|---| | You | Your own leads, their stage, milestones and your earnings. Not which agencies were involved. If another account submitted a creator first, a `409` says only that — and only [20 times a day](https://docs.creator-guard.com/rate-limits/#duplicate-budget). | | Agencies | Offers without her contact details or your notes. Only the agency that accepts her and pays gets her contact details. | | The creator | Her own profile and confirmations, if she has a creator login. | | Creator Guard | Everything, to review, match and support. | ## What the API stores - **The lead and listing** — the fields you send, under your account. - **A request log** per request: key, account, method, endpoint (as a template such as `/v1/leads/{id}`), status, error code, request id, duration and time. **No creator data and no request bodies.** Kept 90 days. Requests without a valid key are not stored there; our server log keeps only their request id, method, endpoint template, status and error code. - **Idempotency answers** for 24 hours, so a retry gets the first answer. - **Your API key** only as a SHA-256 hash, plus its prefix in clear. - **Photos and logos** you upload, re-encoded without any metadata; your original bytes and file names are never stored. See [Photos](https://docs.creator-guard.com/photos/#what-we-do-with-every-file). - **Events** for 30 days, and per webhook delivery the status code, duration and a short error of each attempt — never the body your server answers. Events reference the object; its current state is read when the event is delivered or read. A few events also store a snapshot of their object for the 30 days: a removed photo's metadata (no file, no storage path) and the status of a creator API job or data request — see [Data retention](https://docs.creator-guard.com/data-retention/). - **An audit trail** of key, webhook and account changes for 90 days, with the IP address and client that made them — never secrets or creator data. See [Usage, logs & audit](https://docs.creator-guard.com/usage/#audit-trail). - **Nothing from `POST /v1/extract`**: neither the text you send nor the suggestions. Always use `https://`. ## Minimise what you send Send only what helps place her. `notes` and `notes_public` are free text: no identity documents, passwords, payment details or explicit material. `notes` is for our team only; `notes_public` is shown to agencies. ## Deletion and requests from creators If a creator asks you to delete her data or what we hold about her, forward it to [info@creator-guard.com](mailto:info@creator-guard.com) with her creator number (`CR-…`). How Creator Guard processes personal data: [privacy policy](https://creator-guard.com/privacy). --- # OAuth for creator dashboards Source: https://docs.creator-guard.com/oauth/ > **Note:** > > 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. Your dashboard can act for a creator — read her status, edit her profile, follow her consent — once she signs in with Creator Guard and approves your app. This is OAuth 2.1: the authorization-code flow with PKCE (`S256`) and refresh tokens that rotate on every use. The authorization server is `https://app.creator-guard.com` (the issuer); the API stays on `https://api.creator-guard.com`. If you do not want to build screens for creators, send her our [hosted pages](https://docs.creator-guard.com/hosted-pages/) instead. ## Who can connect to your app She can approve your app only while your account is **approved** and either **submitted her** (you are her referring partner) or, as an agency, **holds a paid reservation for her** (paid, contact released or completed). Anyone else is told on our consent screen that your app cannot connect to her account; the redirect back to you carries `error=access_denied`. We check the relationship again on every token exchange, every refresh and every API call. When it ends (for example a refunded reservation), her grant is revoked: refreshing answers `invalid_grant`, the API `401 invalid_token`. Your account's status is different: while it is pending or disabled, her token answers `403 account_not_active` and refreshing answers `unauthorized_client`, but nothing is revoked — once your account is approved again, the same tokens work. When you remove a team member (or lower her role below admin), every redirect URI that one of her keys added to a live app is removed with her: open codes issued to it stop working, and an authorization whose current refresh token was issued through it is revoked, because that token went to her address. An app left without redirect URIs is **disabled** (`enabled: false`, `disabled_reason: member_offboarded`): the consent screen does not know it and `/oauth/token` answers `unauthorized_client` without revoking anything. Register its redirect URIs again with `PATCH /v1/oauth-apps/{id}` to enable it. Removing a redirect URI yourself has the same effect on what went through it: its open codes fail and refresh tokens issued through it answer `invalid_grant` until it is registered again — keep the old URI registered while you move clients to a new one. The scopes she approves take effect when you exchange the code, not before. She needs her own Creator Guard login for this. A creator without one gets it through a [claim link](https://docs.creator-guard.com/hosted-pages/#claim-link). ### Consent, 18+ and creator terms: never through the referrer's app The account that referred a creator never records her decisions. Her consent, her 18+ confirmation and her acceptance of the creator terms are refused with [`403 referrer_app_not_allowed`](https://docs.creator-guard.com/errors/#referrer_app_not_allowed) when they come through an OAuth app owned by the account that submitted her lead. Apps belong to the account, not to a person, so this covers the app of every member of that account. She gives these only in Creator Guard's own screens: the [consent link](https://docs.creator-guard.com/hosted-pages/#consent-link) or her creator portal. A referrer's app can still read her consent state (`GET /v1/creator/consent`), and **withdrawing** consent works through any connected app, the referrer's included. Claim links are not affected: you can still send her one. Details: [Creator API](https://docs.creator-guard.com/creator-api/#consent-and-18) and [Consent ledger](https://docs.creator-guard.com/consent-ledger/). ## 1. Register your app ```bash curl -X POST https://api.creator-guard.com/v1/oauth-apps \ -H "Authorization: Bearer $CG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Studio Dashboard","privacy_url":"https://example.com/privacy","redirect_uris":["https://dashboard.example.com/oauth/callback"],"scopes":["creator.profile:read","creator.consent:write"],"confidential":true}' ``` The key needs the scope `oauth_apps:manage`. The answer holds `client_id` (`cgcl_live_…`, public) and, for a confidential app, `client_secret` (`cgcs_live_…`) — shown **once**. A browser or mobile app that cannot keep a secret registers with `"confidential": false` and relies on PKCE alone. `POST /v1/oauth-apps/{id}/roll` issues a new secret; the old one keeps working for 24 hours. At most 10 apps per mode. - Redirect URIs are compared character by character: no wildcards, and `…/callback/` is not `…/callback`. - Live apps need `https` and a real host name (no `localhost`, no IP address). Test-mode apps may also use `http://localhost:` and `http://127.0.0.1:`. - `scopes` is the most your app may ask for; each authorize request names the scopes it needs now. The scopes and what she is told about each are listed on [Creator API](https://docs.creator-guard.com/creator-api/#scopes). - Name, logo, privacy policy and your account's name are shown to her on the consent screen. ## 2. Create the PKCE pair Create a new verifier for every sign-in and keep it on your side (server session or browser storage); send only the challenge. ```js // Works in Node 22 and in browsers (Web Crypto). function base64url(bytes) { return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); } export async function challengeFor(verifier) { const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)); return base64url(new Uint8Array(digest)); } export async function pkcePair() { const verifier = base64url(crypto.getRandomValues(new Uint8Array(32))); return { verifier, challenge: await challengeFor(verifier) }; } ``` ```python import base64 import hashlib import secrets def b64url(raw: bytes) -> str: return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii") def challenge_for(verifier: str) -> str: return b64url(hashlib.sha256(verifier.encode("ascii")).digest()) def pkce_pair() -> tuple[str, str]: verifier = b64url(secrets.token_bytes(32)) return verifier, challenge_for(verifier) ``` ## 3. Send her to the authorize URL ```text https://app.creator-guard.com/oauth/authorize?response_type=code &client_id=cgcl_live_3f9c2a7e5b1d4c8fa06e2b9d7c4a1f53 &redirect_uri=https%3A%2F%2Fdashboard.example.com%2Foauth%2Fcallback &scope=creator.profile%3Aread%20creator.consent%3Awrite &state=8c1f0e… (random, 1 to 500 characters, stored in her session) &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256 ``` (One line in practice.) `state` and `code_challenge_method=S256` are required; `plain` is refused, and so is any parameter sent twice. She signs in with her own Creator Guard email and password, sees your app's name, logo, owner and each scope in plain words, and allows or denies. The screen serves live apps only. An unknown `client_id` or a `redirect_uri` that is not registered shows an error page and never redirects. The page cannot be framed: open it in the top window or a new tab. ## 4. Handle the redirect We send her back to your redirect URI with `?code=…&state=…&iss=https%3A%2F%2Fapp.creator-guard.com`. First compare `state` with the one you stored and `iss` with the issuer; if either differs, stop. On a denial or error the query holds `error` (`access_denied`, `invalid_scope`, `invalid_request`, `unsupported_response_type`), `error_description`, the same `state` and `iss`. A code is valid for **60 seconds** and **once**: a second use fails and revokes the grant, with every token issued from it. ## 5. Exchange the code ```bash curl -X POST https://app.creator-guard.com/oauth/token \ -u "$CLIENT_ID:$CLIENT_SECRET" \ -d grant_type=authorization_code -d code="$CODE" -d code_verifier="$VERIFIER" \ --data-urlencode redirect_uri=https://dashboard.example.com/oauth/callback ``` ```js const res = await fetch('https://app.creator-guard.com/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'authorization_code', code: process.env.CG_CODE, code_verifier: process.env.CG_VERIFIER, redirect_uri: 'https://dashboard.example.com/oauth/callback', client_id: process.env.CG_CLIENT_ID, client_secret: process.env.CG_CLIENT_SECRET, // confidential apps only, server side only }), }); const tokens = await res.json(); // { access_token, token_type: 'Bearer', expires_in: 3600, refresh_token, scope } ``` ```python import json import os import urllib.parse import urllib.request def exchange(code: str, verifier: str) -> dict: body = urllib.parse.urlencode({ "grant_type": "authorization_code", "code": code, "code_verifier": verifier, "redirect_uri": "https://dashboard.example.com/oauth/callback", "client_id": os.environ["CG_CLIENT_ID"], "client_secret": os.environ["CG_CLIENT_SECRET"], # confidential apps only }).encode() req = urllib.request.Request("https://app.creator-guard.com/oauth/token", data=body, method="POST") with urllib.request.urlopen(req) as res: return json.load(res) ``` Confidential apps authenticate with HTTP Basic (`client_secret_basic`) or with `client_id` + `client_secret` in the body (`client_secret_post`); public apps send only `client_id` (`none`). The access token (`cgo_live_…`) lasts 1 hour, the refresh token (`cgr_live_…`) 30 days from its last use. Store both like passwords — we keep only their hashes and cannot show them again. Every answer is `Cache-Control: no-store`. If a client secret or a token turns up in public (GitHub secret scanning reports `cgcs_`, `cgo_` and `cgr_` values to us, like API keys), we act at once, without asking first: a leaked client secret is replaced by one nobody knows — the app cannot authenticate until you roll a new one with `POST /v1/oauth-apps/{id}/roll` (a leaked previous secret, still accepted after a roll, simply stops working); a leaked access or refresh token ends the creator's whole authorization, and she has to connect your app again. Your audit events show `oauth_app.secret_leaked` or `oauth_app.token_leaked`, and we email your account's contact address. ### Browser apps (CORS) **The API itself is server-side only: `/v1` sends no CORS headers**, so a browser page cannot read any `/v1` answer — the creator API included. A browser or mobile front end calls your own backend, and your backend calls `https://api.creator-guard.com` with the access token. Only the sign-in endpoints have CORS: - `/oauth/token` and `/oauth/revoke`: a public client running in the browser may call them directly. The answer is readable only from the **origin of one of the app's registered redirect URIs** (`Access-Control-Allow-Origin` names exactly that origin; any other origin gets no CORS header). The preflight allows only `POST` with `Content-Type` — no `Authorization` header, so a client secret can never be sent from a browser. Confidential apps call these endpoints from their server. - `/.well-known/oauth-authorization-server` (the server metadata) is readable from any origin (`Access-Control-Allow-Origin: *`); it holds nothing secret. - `/oauth/authorize` is a page the creator's browser navigates to, not something to fetch. ## 6. Call the creator API ```bash curl https://api.creator-guard.com/v1/creator/me -H "Authorization: Bearer $ACCESS_TOKEN" ``` Every endpoint is listed on [Creator API](https://docs.creator-guard.com/creator-api/). A token without the scope an endpoint needs gets `403 insufficient_scope`; an expired one `401 expired_token`; a revoked one `401 invalid_token`. An account API key on a creator endpoint is `403 wrong_account_type`. Requests count against your account's limits, per grant. ## Refresh tokens rotate ```bash curl -X POST https://app.creator-guard.com/oauth/token -u "$CLIENT_ID:$CLIENT_SECRET" \ -d grant_type=refresh_token -d refresh_token="$REFRESH_TOKEN" ``` Every refresh returns a **new** refresh token and invalidates the old one. Save the new one before you use the new access token. A `scope` sent with a refresh is ignored: the answer states the grant's scopes. > **Important:** > > Never send an old refresh token again. If a refresh token that was already rotated arrives a second time, we treat it as stolen: the whole grant is revoked, every access and refresh token of it stops working (`invalid_grant`, then `401 invalid_token`), and she has to approve your app again. Run refreshes in one place (no two workers refreshing the same grant at once), and if a refresh fails with a network error, do not retry it with the same token — send her through authorize again. ## Revoke ```bash curl -X POST https://app.creator-guard.com/oauth/revoke -u "$CLIENT_ID:$CLIENT_SECRET" -d token="$REFRESH_TOKEN" ``` Revoking a refresh token ends the grant; revoking an access token ends only that token. The answer is `200` whether or not the token existed (RFC 7009). She can also disconnect your app herself in the creator portal, and your app can disconnect itself through `DELETE /v1/creator/connected-apps/{app}` with its own app id (scope `creator.profile:write`; other apps' ids are `404`); deleting your app (`DELETE /v1/oauth-apps/{id}`) revokes every grant it has. ## Consent texts and `409 consent_text_outdated` Before you record her consent, her 18+ confirmation or her acceptance of the creator terms, fetch the current text with `GET /v1/creator/consent-text?kind=consent` (`age_confirmation`, `creator_terms`), show `body_md` to her unchanged, and send its `version` with her answer (`POST /v1/creator/consent/grant` with `{"text_version": 1}`). We record the version and the text's hash in the [consent ledger](https://docs.creator-guard.com/consent-ledger/). When we publish a new wording, the old version is refused with `409 consent_text_outdated` (`error.current_version` names the new one) and nothing is recorded: fetch the new text, show it to her, and ask again. Never retry with the new version number without showing her the new text. A **withdrawal** (`POST /v1/creator/consent/revoke`) never fails because of the text version: she can always take her consent back. ## Test mode Test-mode apps (`cgcl_test_…`, registered with a `cg_test_` key) work against the sandbox. Our consent screen serves live apps only, because the sandbox has no real creator logins. Instead, mint a code with your test key (scope `oauth_apps:manage`) for a sandbox lead you submitted: ```bash curl -X POST https://api.creator-guard.com/v1/test-helpers/oauth-codes \ -H "Authorization: Bearer $CG_TEST_KEY" -H "Content-Type: application/json" \ -d '{"client_id":"cgcl_test_3f9c2a7e5b1d4c8fa06e2b9d7c4a1f53","lead_id":"lead_eaaaaaaaabaabaaaaaaaaaaaae","redirect_uri":"http://localhost:3000/callback","scopes":["creator.profile:read"],"code_challenge":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"}' ``` The answer is `{"object": "oauth_test_code", "code": "cgac_…", "expires_in": 60}`. Exchange the `code` at `/oauth/token` exactly as in step 5; the tokens start with `cgo_test_` / `cgr_test_` and only ever see test data. Refresh, reuse detection and revoke behave as in live mode. A live key gets `404 not_found` from every test helper. ## Errors of the OAuth endpoints `/oauth/token` and `/oauth/revoke` answer like RFC 6749: `{"error": "invalid_grant", "error_description": "…"}`. | `error` | HTTP | Meaning | |---|---|---| | `invalid_request` | 400 | A parameter is missing or repeated, or the verifier is not 43 to 128 characters | | `invalid_client` | 401 | Unknown `client_id`, wrong secret, a secret from a public client, or none from a confidential one | | `invalid_grant` | 400 | Code or refresh token unknown, used, expired or revoked; `redirect_uri` or verifier does not match; the relationship to her ended | | `unauthorized_client` | 400 | Your account is not approved right now; nothing was revoked | | `unsupported_grant_type` | 400 | Only `authorization_code` and `refresh_token` | | `server_error` | 500 | Something failed on our side; try again | | `temporarily_unavailable` | 503 | OAuth is not configured on our side; try again later | | `rate_limited` | 429 | Too many refused requests from your IP address; wait for `Retry-After` | `/oauth/token`, `/oauth/revoke`, the authorize page and its decision share the per-IP budget of requests without an account (30 per minute per IP). Successful token and revoke calls spend nothing, so refreshing many tokens from your server is never throttled; refused ones (a wrong secret, an unknown code) do. The API itself answers with the usual error object; see [Errors](https://docs.creator-guard.com/errors/). ## Server metadata `GET https://app.creator-guard.com/.well-known/oauth-authorization-server` (RFC 8414) lists the issuer `https://app.creator-guard.com`, the authorization, token and revocation endpoints, `code_challenge_methods_supported: ["S256"]`, the client authentication methods and the scopes. --- # Creator API endpoints Source: https://docs.creator-guard.com/creator-api/ A creator token (`Authorization: Bearer cgo_live_…`, see [OAuth](https://docs.creator-guard.com/oauth/)) acts for exactly one creator, through one app, with the scopes she approved. Paths are under `https://api.creator-guard.com/v1`. Every field, status and error is in the [reference](https://docs.creator-guard.com/reference/). An account API key on these endpoints gets `403 wrong_account_type`. | Endpoint | Scope | What it does | |---|---|---| | `GET /creator/me` | `creator.profile:read` | Her name, stage, next steps and — once an agency paid for her — that agency | | `GET /creator/profile`, `PATCH /creator/profile` | `creator.profile:read` / `creator.profile:write` | Her contact fields and the listing fields she edits in the creator portal; never fees, deal terms or the OnlyFans verification flag | | `POST /creator/submit-for-review` | `creator.profile:write` | Same rules as for partners: open blockers → `422 not_ready_for_review` (`fee_missing`: her referral partner still has to set the fee) | | `GET /creator/photos`, `POST /creator/photos`, `DELETE /creator/photos/{photo}` | `creator.photos:write` | Her photos, re-encoded and stripped of metadata on our side; frozen once her listing is live (`409 photos_locked`) | | `GET /creator/consent-text` | `creator.profile:read` | The current text (`kind` = `consent`, `age_confirmation`, `creator_terms`) to show before she decides | | `GET /creator/consent` | `creator.profile:read` | Consent and 18+ state with her ledger entries | | `POST /creator/consent/grant`, `POST /creator/consent/revoke` | `creator.consent:write` | Records her consent (current text version; also her 18+ confirmation, which the consent text includes; `409 invalid_state` while her 18+ check is declined or under review) or its withdrawal (never refused) | | `POST /creator/age-confirmation` | `creator.consent:write` | Records that she confirms she is 18 or over | | `GET /creator/agreements`, `POST /creator/agreements/{type}/accept` (`type` = `creator_terms`) | `creator.consent:write` | Creator terms: current version and her acceptance | | `GET /creator/support-tickets`, `POST /creator/support-tickets`, `GET /creator/support-tickets/{id}/messages`, `POST /creator/support-tickets/{id}/messages`, `POST /creator/support-tickets/{id}/close` | `creator.support` | Her conversations with our team | | `POST /creator/data-export`, `GET /creator/data-export/{id}` | `creator.privacy` | A copy of her data (asynchronous) | | `POST /creator/deletion-request` | `creator.privacy` | Asks us to delete her data | | `GET /creator/connected-apps`, `DELETE /creator/connected-apps/{app}` | `creator.profile:read` / `creator.profile:write` | Your own app's connection only; disconnect your app (any other app id is `404`). Her full list of connected apps is shown only to her, in the creator portal | | `GET /jobs/{id}` | `creator.privacy` (for a data export) | The status of an asynchronous job | ## Scopes What she reads on the consent screen for each scope: | Scope | Shown to her | |---|---| | `creator.profile:read` | See your profile, where you stand and which agency you are matched with | | `creator.profile:write` | Change your profile and send it to Creator Guard for review | | `creator.photos:write` | Upload and delete your photos | | `creator.consent:write` | Record your consent decisions: your consent or its withdrawal, your 18+ confirmation and your acceptance of the creator terms — an app of the partner who introduced you can only see and withdraw your consent, never give it | | `creator.support` | Read and write your support messages with the Creator Guard team | | `creator.privacy` | Send this app a copy of your data, including your support messages, or ask for your data to be deleted | ## Edit windows Her contact fields (`lead`: handle, other contact, platforms, followers, niche) can change while her lead is `submitted` (`409 lead_locked` afterwards); listing fields and photos until the listing is live (`409 listing_locked`, `409 photos_locked`). `GET /creator/profile` tells you with `can_edit_lead` and `can_edit_listing` and sends an `ETag` — send it back as `If-Match` so you do not overwrite a change she made in the portal (`412 precondition_failed`). ## Consent and 18+ **Not through the referrer's app.** If your account submitted her lead (you are her referring partner), `POST /creator/consent/grant`, `POST /creator/age-confirmation` and `POST /creator/agreements/{type}/accept` answer [`403 referrer_app_not_allowed`](https://docs.creator-guard.com/errors/#referrer_app_not_allowed) through any of your account's apps and record nothing — whatever her current state. She gives consent, confirms 18+ and accepts the creator terms only in Creator Guard's own screens: the [consent link](https://docs.creator-guard.com/hosted-pages/#consent-link) (which you can still send) or her creator portal. `GET /creator/consent` keeps working, and `POST /creator/consent/revoke` works through any connected app, yours included. [Claim links](https://docs.creator-guard.com/hosted-pages/#claim-link) work as before. Show her the text from `GET /creator/consent-text` in full and unchanged, then send its `version` as `text_version` with her decision. A grant, the 18+ confirmation or the creator terms with an older version are refused with `409 consent_text_outdated` and nothing is recorded. Her **withdrawal is never refused** because of the text version: send the version she saw if you have it, otherwise none. Every decision becomes an entry of her [consent ledger](https://docs.creator-guard.com/consent-ledger/) with the channel `oauth_app:app_…`. Ledger entries returned to your app never contain an IP address or browser. ## Data export (async) `POST /creator/data-export` answers `202` with a job (`job_…`, `Location: /v1/jobs/job_…`); `GET /v1/jobs/{id}` shows its progress. When it succeeded, the job's `result.data_request` names the export, your account receives the events `data_export.ready` and `job.completed`, and `GET /creator/data-export/{id}` returns a signed `download_url` (a JSON file). Each call signs a new link that works for **1 hour** at most (`download_url_expires_at`); the file itself is kept until `expires_at`, 7 days after it was ready — download it right away and ask again for a new link later. The export is bound to your app: only the app that asked for it can read it (and its job); another of her connected apps gets `404 not_found` for that id and asks for its own export. Record ids in the file are public ids (`lead_…`, `photo_…`, `cev_…`, `tkt_…`, `dreq_…`); apps appear by name. One export per app per 24 hours: asking again returns your app's open or recent job. The file holds what we keep about her that she may see, including her support conversations with us — no fees, deal terms, partner notes, IP addresses or browsers. The consent screen tells her that your app receives this copy. It is not a complete statement of everything we hold about her (Article 15 GDPR); for that she can write to [info@creator-guard.com](mailto:info@creator-guard.com), and we answer her directly. ## Deletion `POST /creator/deletion-request` creates a task for our team (or returns the open one). When we have carried it out — her personal data, photos, login and grants are deleted, the IP addresses and browsers in her consent records erased — your account receives `deletion_request.completed`. From then on every token for her stops working; delete her data in your systems too. ## Events for your account The three events above go to the account that owns the app, as webhooks and in `GET /v1/events`, read with the key scope `oauth_apps:manage`. They carry only a reference (`{"id": "dreq_…", "object": "data_request"}` or `{"id": "job_…", "object": "job"}`), never her data: fetch the details with her token. See [Events](https://docs.creator-guard.com/events/). ## Only on our hosted pages Her password, email address and sign-in change only on our hosted pages (claim page, creator portal, password reset), never through the API. --- # Consent ledger Source: https://docs.creator-guard.com/consent-ledger/ Agencies see a creator's photos only after she consented, and only once she confirmed she is 18 or over. We keep every such step as an entry in an append-only ledger: entries are only ever added. The database allows two exceptions and nothing else: when her data is deleted at her request, the IP address and browser are erased from her entries (the rest stays), and entries disappear only together with her lead record — which we anonymise rather than delete, so in practice they stay. Her current state (`GET /v1/creator/consent`, the `confirmations` of a lead) is computed from it, and her photos are released only by it. ## What an entry holds | Field | Meaning | |---|---| | `kind` | `consent_granted`, `consent_revoked`, `age_confirmed`, `creator_terms_accepted` | | `text_kind`, `text_version` | Which text she was shown (`consent`, `age_confirmation`, `creator_terms`), and which version of it | | `sha256` of the text | Stored with the entry, so the exact wording can be proven later | | `channel` | Where she acted (below); for an app we also keep the app's name at that moment, even if the app is deleted later | | IP address, browser, time | Where the request came from and when | The IP address and browser are evidence for Creator Guard. They are shown only to the creator herself in her portal and to our team — **never to partner or agency apps**: ledger entries returned through the API (`GET /v1/creator/consent`) carry kind, text version, channel and time only, and her data export (which goes to the app that asked for it) leaves them out too. ## Channels — equal evidence | `channel` | Where she acted | |---|---| | `hosted_link` | The consent page behind a consent link (`/creator-consent/`) | | `hosted_portal` | Her creator portal on `app.creator-guard.com` | | `oauth_app:` (e.g. `oauth_app:app_…`) | Your dashboard, through `POST /v1/creator/consent/grant`, `…/revoke`, `/v1/creator/age-confirmation` or the creator-terms accept — never the app of the account that referred her, except for a withdrawal (see below) | | `admin` | Our team, on her documented request | | `legacy` | Decided before the ledger existed; how she answered was not recorded | **The referrer's app records no decision.** Consent, the 18+ confirmation and the creator terms are never recorded through an OAuth app owned by the account that submitted her lead — apps belong to the account, so this covers every member's app of it. Such a call answers [`403 referrer_app_not_allowed`](https://docs.creator-guard.com/errors/#referrer_app_not_allowed) and nothing is written; she decides in Creator Guard's own screens instead (the consent link or her creator portal). Her withdrawal is the exception: it is accepted through any connected app, the referrer's included. Reading her consent state is not affected. Every channel records the same fields. For an `oauth_app:` channel the IP address and browser are those of **your server's request**, not hers — so your dashboard must show her the exact text from `GET /v1/creator/consent-text`, unchanged, and send its `text_version` only after she actively agreed. Keep your own record of that moment too. Texts change only as a new version (version 2 of the consent and 18+ texts went live with the 2026-10 release, in English; other languages fall back to the English text): a grant, 18+ confirmation or terms acceptance naming an older version answers `409 consent_text_outdated` with `current_version`, so fetch the text again and show it to her. ## Consent includes 18+ The consent text includes her confirmation that she is 18 or over. So every channel records a grant the same way: a `consent_granted` entry and, unless her 18+ is already confirmed, an `age_confirmed` entry on the same consent text and version. While our team has declined her 18+ check or is still reviewing a document, a grant is refused with `409 invalid_state` (`error.current_state` `age_declined` or `age_pending`) and records nothing; she should contact our support. ## Versioned texts Each text (`consent`, `age_confirmation`, `creator_terms`) has numbered versions per language; a published version never changes. A new wording is a new version. Granting consent, confirming 18+ or accepting the creator terms with an older `text_version` gets `409 consent_text_outdated` (`error.current_version` names the current one) and records nothing — show her the new text and ask again. ## Withdrawal She can withdraw consent at any time — on the consent page (even after the link has expired: an expired link can no longer grant, but it still withdraws), in the creator portal or through your app (`consent_revoked`). A withdrawal is **never refused because of the text version**: it records the version it was sent if that version exists, otherwise the current one. Her photos stop being shown to agencies at once. The earlier entries stay: the ledger records history, it does not rewrite it. When her data is deleted at her request, her ledger entries keep their kind, version and time, but lose the IP address and browser. Two internal references stay on each entry as pseudonymous identifiers: the id of the login that recorded it (the login itself is deleted, so it no longer points to anyone) and the id of the app connection it came through (the connection is deleted with her login). They keep the record consistent and cannot be traced back to her without data we no longer hold. --- # Hosted pages for creators Source: https://docs.creator-guard.com/hosted-pages/ You do not have to build anything for creators. Create a link with your API key, send it to her, and she does the rest on our pages on `app.creator-guard.com`. Building your own screens is the alternative: [OAuth](https://docs.creator-guard.com/oauth/). ## Consent link `POST /v1/leads/{id}/consent-link` (also in `consent.url` of the `201` that created a lead) returns a URL `https://app.creator-guard.com/creator-consent/`, valid for 30 days. We store links only as hashes, so a link is shown once: each call makes a new link, and the previous one can then only be used to withdraw a consent (like an expired link). She reads the consent text, agrees (or declines) and confirms she is 18 or over. After the 30 days the link can no longer be used to agree, but she can still withdraw a consent she gave through it. Each step is recorded in the [consent ledger](https://docs.creator-guard.com/consent-ledger/) with the channel `hosted_link`. ## Claim link `POST /v1/leads/{id}/claim-link` (scope `leads:write`) returns `https://app.creator-guard.com/claim/`, valid for **7 days** and usable **once**. On that page she chooses her own email address and password (at least 10 characters) for the creator portal — you never see or set her password, and nobody else can. The URL is shown once (`url: null` in an `Idempotency-Key` replay); a new claim link makes the previous one invalid. A lead whose creator already has a login, or that was withdrawn or rejected, gets `409 invalid_state` (`current_state` `claimed`, `withdrawn` or `rejected`) instead of a link. If no login can be set up with the email address she enters (for example because it already has one), the page says so in neutral words — it never confirms that an address is registered — and asks her to sign in instead or to use another address. A link takes at most 5 submissions per hour, and after 10 failed attempts (login not set up, password refused) it stops working; create a new one. Her login is what she signs in with on our [OAuth](https://docs.creator-guard.com/oauth/) consent screen when she connects your app. The login works as soon as the form is sent. So that nobody can quietly claim it in her place, we record when the link was used, from which IP address and browser, and which account issued it. She sees this in her creator portal ("Your login was set up on …"), and our team sees it; it is never shared with partners, agencies or apps. The page tells her so before she sends the form, with a link to our privacy policy. Send the link only to her. ## Creator portal After claiming, she signs in at `https://app.creator-guard.com/creator-portal`: her status, profile and photos, consent and 18+, creator terms, support tickets, and the apps she connected (she can disconnect any of them there). A forgotten password is reset from the login page (`/reset-password`) once password e-mails are switched on; until then our support helps her. ## Embedding Our hosted pages and the OAuth screens cannot be shown inside a frame (`X-Frame-Options: DENY`, `frame-ancestors 'none'`), send no referrer and are never cached. Link to them, open them in a new tab, or redirect — never embed them in an iframe. --- # API reference Source: https://docs.creator-guard.com/reference/ > **Note:** > > **Machine-readable contract:** [`openapi.yaml`](https://docs.creator-guard.com/openapi.yaml) (OpenAPI 3.1) — import it into Postman, Insomnia or a code generator; the [SDKs](https://docs.creator-guard.com/sdks/) are generated from it. **For AI agents:** [`llms-full.txt`](https://docs.creator-guard.com/llms-full.txt) holds this reference and every guide page as one Markdown file — see [Build with AI agents](https://docs.creator-guard.com/ai-agents/). ## API reference (OpenAPI 3.1.0, API version 1.23.0) Generated from https://docs.creator-guard.com/openapi.yaml — the machine-readable contract; import it into a code generator or HTTP client. Base URL: `https://api.creator-guard.com` (paths below start with `/v1`). Production. `cg_live_` keys work on live data, `cg_test_` keys on the sandbox (test mode) — same host, same paths. Authentication: HTTP bearer — cg_live_ (or cg_test_) followed by 43 letters and digits. `Authorization: Bearer cg_live_…`. Keys are issued by Creator Guard per account and handed over once; only a hash is stored. A key carries scopes (each operation names the one it needs), an optional expiry and an optional IP allowlist. `cg_test_` keys work in test mode (sandbox data, halved limits). ### Service #### API status and versions `GET /v1/` · operationId `getApi` Auth: none (no API key needed). No key needed. Use it as a liveness check and to read the contract version. Like every request without a valid key it uses the per-IP budget (30 per minute), so poll it at most every few seconds. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ApiInfo` | The API document. | Error statuses: 429, 500 — body `ErrorResponse`; codes per status under "Error responses by status". ### Account #### The account the key belongs to `GET /v1/me` · operationId `getAccount` Auth: API key with scope `account:read` · account types: any. Type, status, terms state per agreement type and the limits in effect for this key. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Account` | The account. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Change your account profile `PATCH /v1/me` · operationId `updateAccount` Auth: API key with scope `account:write` · account types: any. Display name, company name, Telegram username and website — the same fields and checks as the portal's profile page. Send only what changes; `null` (or an empty string) clears the company name or the website. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. | Request body (`application/json`): `AccountPatch` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Account` | The account. | Error statuses: 400, 401, 403, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Agreements and your acceptances `GET /v1/agreements` · operationId `listAgreements` Auth: API key with scope `account:read` · account types: any. The current published version of every agreement type that applies to the account, with the account's acceptance. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `AgreementList` | Agreements that apply to the account. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Full text of one agreement version `GET /v1/agreements/{type}/{version}` · operationId `getAgreementText` Auth: API key with scope `account:read` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `type` | path | string | required | `referrer_terms`, `agency_terms`, `warranty_terms`, `api_terms` or `api_dpa`. | | `version` | path | integer · ≥ 1 | required | | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `AgreementDocument` | One agreement version with its text. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Accept the current version of an agreement `POST /v1/agreements/{type}/accept` · operationId `acceptAgreement` Auth: API key with scope `agreements:write` · account types: any. Only the current published version can be accepted (an older one → `409 invalid_state` with `error.current_version`). Records the key, the caller's IP address and user agent. Works before the terms are accepted — it is how you accept them. `api_terms` (the [API Terms](https://docs.creator-guard.com/authentication/#api-terms)) and `api_dpa` (the [data protection addendum](https://docs.creator-guard.com/authentication/#data-protection-addendum)) belong to the account: accepted once, with a live or a test key, they apply to both modes. Only keys of an owner or admin carry `agreements:write`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `type` | path | string | required | `referrer_terms`, `agency_terms`, `warranty_terms`, `api_terms` or `api_dpa`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `AgreementAccept` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Agreement` | The agreement with your acceptance. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_state` (all codes: Error codes below). #### The portal's pick lists `GET /v1/option-lists` · operationId `getOptionLists` Auth: API key with scope `account:read` · account types: any. Values that match what agencies search for. Full lists: https://docs.creator-guard.com/reference/allowed-values/ Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `OptionLists` | The pick lists. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Brokerage numbers `GET /v1/settings` · operationId `getSettings` Auth: API key with scope `account:read` · account types: any. Offer deadline, undo window, payment due days, warranty days and the Creator Guard share of a fee. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Settings` | Brokerage numbers. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Upload your logo `PUT /v1/me/logo` · operationId `setLogo` Auth: API key with scope `account:write` · account types: any. `multipart/form-data` with one part `file`: PNG, JPEG or WebP, at most 2 MB. We re-encode it (at most 512 px on the long edge, every metadata block removed) and replace the old logo. Counts against the upload limit of the account (60 per minute, 3,000 per day, halved in test mode). Request body (`multipart/form-data`): `LogoUpload` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Account` | The account. | Error statuses: 400, 401, 403, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Remove your logo `DELETE /v1/me/logo` · operationId `deleteLogo` Auth: API key with scope `account:write` · account types: any. Removes the file, then the logo. If the file cannot be removed, nothing changes and the answer is `502 upstream_failed` — retry. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Account` | The account. | Error statuses: 401, 403, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `upstream_failed` (all codes: Error codes below). ### Leads #### List your leads `GET /v1/leads` · operationId `listLeads` Auth: API key with scope `leads:read` · account types: any. Newest first (`created_at`, then `id`). Filters combine with AND. Unknown parameters → `400 unknown_parameter`; an invalid filter value → `400 invalid_field`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). | | `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. | | `ending_before` | query | string | optional | Id of the first item of the current page: the page before. | | `stage` | query | string · one of `draft`, `in_review`, `ready`, `offered`, `accepted`, `in_placement`, `placed`, `rejected`, `lost`, `withdrawn` | optional | One stage (see the Lead schema). | | `external_id` | query | string · 1–200 chars | optional | Your own reference, exact match. | | `creator_ref` | query | string · pattern `^(?:[Cc][Rr][ -]?)?[0-9]{1,9}$` | optional | Creator number, `CR-1047` or `1047`. | | `instagram_handle` | query | string · 1–200 chars | optional | Handle or profile link; compared after normalising. | | `q` | query | string · 1–200 chars | optional | Part of the creator name, case-insensitive. | | `created_since` | query | string (date-time) | optional | Leads created at or after this instant (RFC 3339, e.g. `2026-10-09T12:00:00Z`). | | `updated_since` | query | string (date-time) | optional | Leads changed at or after this instant — for incremental sync. | | `has_blockers` | query | boolean | optional | `true`: only leads with `next_actions.blockers`; `false`: only without. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `LeadList` | A page of leads. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `unknown_parameter`, `invalid_field` (all codes: Error codes below). #### Create a lead `POST /v1/leads` · operationId `createLead` Auth: API key with scope `leads:write` · account types: any. Creates a lead for one creator under your account, optionally with her listing. Only `creator_name` and `consent_confirmed` are required (the portal's rule); send every other field you have. Without an `instagram_handle` there is no duplicate check by handle: use `external_id` so a retry finds her again. - **201** — a new lead was created. - **200** — nothing new was created: you already used this `external_id` (that lead is returned unchanged), or you already submitted this Instagram handle and that lead is still a `draft` (it is updated with the lead fields you sent; a `listing` in the body is applied like `PATCH …/listing`). - **409 `duplicate_own_lead`** — your lead with this handle is past `draft`. Nothing changes; `error.lead`. - **409 `duplicate_other_referrer`** — another account submitted this handle. Budgeted: 20 such answers per rolling 24 h, then `429 duplicate_limit_reached` for every request with an `instagram_handle`. Both answers carry `consent`. The `201` carries her personal consent link in `consent.url` (valid at least 30 days) — send it to her. Links are stored only as hashes, so the `url` is shown only there: a `200`, a `GET` and an `Idempotency-Key` replay answer `url: null`; `POST /v1/leads/{id}/consent-link` makes a new one. Send an `Idempotency-Key` so a retry after a timeout returns the first answer. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `LeadCreate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Lead` | Already known: your `external_id`, or your handle while that lead is still a draft. `consent` carries her consent link. | | 201 | `Lead` | A new lead was created; `consent` carries her consent link. | Error statuses: 400, 401, 403, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `duplicate_own_lead`, `duplicate_other_referrer`, `duplicate_limit_reached` (all codes: Error codes below). #### Get a lead `GET /v1/leads/{id}` · operationId `getLead` Auth: API key with scope `leads:read` · account types: any. With `?expand=listing,photos,confirmations` (any combination) the lead carries those objects too. Any other query parameter → `400 unknown_parameter`, another `expand` value → `400 invalid_field`. `consent` shows her consent link as it is; reading never extends it. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `expand` | query | string | optional | Comma-separated: `listing`, `photos`, `confirmations`. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Lead` | The lead, with her consent link (`consent`). | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `unknown_parameter`, `invalid_field` (all codes: Error codes below). #### Change lead fields `PATCH /v1/leads/{id}` · operationId `updateLead` Auth: API key with scope `leads:write` · account types: any. Lead fields only while the lead is a `draft` (`next_actions.can_edit_lead`), else `409 lead_locked`. `external_id` can be changed at any stage (unique within your account, else `409 external_id_taken`). Both `instagram_handle` and `other_contact` may be cleared (`null`), as in the portal. A new `instagram_handle` that another account already submitted → `409 duplicate_other_referrer` (counts against the same daily budget as on create, then `429 duplicate_limit_reached`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. | Request body (`application/json`): `LeadUpdate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Lead` | The lead. | Error statuses: 400, 401, 403, 404, 409, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `duplicate_other_referrer`, `lead_locked`, `external_id_taken`, `duplicate_limit_reached` (all codes: Error codes below). #### Withdraw a lead `POST /v1/leads/{id}/withdraw` · operationId `withdrawLead` Auth: API key with scope `leads:write` · account types: any. Allowed while `next_actions.can_withdraw` (`draft` or `in_review`, no live offer); else `409 invalid_state`. No body. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Lead` | The lead. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_state` (all codes: Error codes below). #### Suggest lead fields from text `POST /v1/extract` · operationId `extractFields` Auth: API key with scope `extract` · account types: any. Paste a profile text, a chat or notes (20–20,000 characters); the answer suggests lead and listing fields for you to review. Nothing is stored — not the text, not the suggestions — so an `Idempotency-Key` is ignored and a retry simply runs again. Limits: 20 per minute and 200 per day per account (halved in test mode). With a `cg_test_` key the answer is a fixed fictitious example and no AI runs. Works before the terms are accepted. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string | optional | Ignored on this endpoint: nothing is stored, a retry runs again. | Request body (`application/json`): `ExtractRequest` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ExtractResult` | Suggested fields; nothing was stored. | Error statuses: 400, 401, 403, 413, 415, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status". ### Listing #### Get the listing of a lead `GET /v1/leads/{id}/listing` · operationId `getListing` Auth: API key with scope `leads:read` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Listing` | The listing. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Change listing fields `PATCH /v1/leads/{id}/listing` · operationId `updateListing` Auth: API key with scope `leads:write` · account types: any. While the listing is not live (`next_actions.can_edit_listing`), else `409 listing_locked`. `placement_fee` only while `next_actions.can_edit_fee`. Send `null` to clear a value, `[]` to empty a list. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. | Request body (`application/json`): `ListingPatch` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Listing` | The listing. | Error statuses: 400, 401, 403, 404, 409, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `listing_locked` (all codes: Error codes below). #### Submit a draft for review `POST /v1/leads/{id}/submit-for-review` · operationId `submitForReview` Auth: API key with scope `leads:write` · account types: any. Draft → in review (`next_actions.can_submit_for_review`). Remaining blockers → `422 not_ready_for_review` with `error.blockers`, `fee_missing` included: set `placement_fee` before you submit her. Not a draft → `409 invalid_state`. No body. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Lead` | The lead. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_state`, `not_ready_for_review` (all codes: Error codes below). #### Her consent, 18+ confirmation and login state `GET /v1/leads/{id}/confirmations` · operationId `getConfirmations` Auth: API key with scope `leads:read` · account types: any. Status and dates only — never her IP address or browser. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Confirmations` | Her confirmations. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Her personal consent link `POST /v1/leads/{id}/consent-link` · operationId `createConsentLink` Auth: API key with scope `leads:write` · account types: any. Returns the hosted page where she confirms consent and 18+ herself: a NEW link, valid at least 30 days from now. Links are stored only as hashes, so each call makes a new one; the previous link of the lead can then only be used to withdraw consent (never to give it). An `Idempotency-Key` replay answers `url: null`. Send the link to her; never confirm for her. After her data was erased on her request → `409 invalid_state` with `error.current_state` `anonymized`. No body. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ConsentLink` | Her consent link. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_state` (all codes: Error codes below). #### Her claim link (her own login) `POST /v1/leads/{id}/claim-link` · operationId `createClaimLink` Auth: API key with scope `leads:write` · account types: any. A single-use link to the hosted page where she chooses her own email and password for the creator portal. It works once and for 7 days; a new link makes every earlier unused link of the lead invalid. The URL is shown only in this answer: an `Idempotency-Key` replay returns the same object with `url: null` (call again without the key for a new link). A `cg_test_` key gets a `…/claim/test_…` URL that opens a notice only. `409 invalid_state` with `error.current_state` `claimed` (she already has a login), `withdrawn` or `rejected`. No body. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 201 | `ClaimLink` | Her claim link (shown once). | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_state` (all codes: Error codes below). #### Milestones of a lead `GET /v1/leads/{id}/timeline` · operationId `getTimeline` Auth: API key with scope `leads:read` · account types: any. Submitted, review requested, approved, offers, acceptance, payment, warranty, completion, commission. No agency names. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Timeline` | The milestones. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Your earnings from a lead `GET /v1/leads/{id}/earnings` · operationId `getEarnings` Auth: API key with scope `earnings:read` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Earnings` | Your earnings. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". ### Photos #### List her photos `GET /v1/leads/{id}/photos` · operationId `listPhotos` Auth: API key with scope `leads:read` · account types: any. Primary photo first, then oldest first; every photo on one page. Each `url` is signed and works for one hour. No query parameters besides `fields`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `PhotoList` | Her photos, primary first. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Upload a photo `POST /v1/leads/{id}/photos` · operationId `uploadPhoto` Auth: API key with scope `photos:write` · account types: any. `multipart/form-data`: `file` (JPEG, PNG or WebP, at most 40 MB and 50 megapixels), optionally `kind` (default `portrait`) and `is_primary`. We read the format from the bytes, bake in the orientation, scale to at most 3000 px on the long edge and remove **every** metadata block (EXIF, GPS, XMP, IPTC) before anything is stored; your original bytes are never kept, nor the file name. At most 20 photos per lead (`409 limit_reached`); only while the listing is not live (`409 photos_locked`). Counts against the upload limit (60 per minute, 3,000 per day, halved in test mode). A replay of the same `Idempotency-Key` answers `url: null`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`multipart/form-data`): `PhotoUpload` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 201 | `Photo` | The photo was stored (re-encoded, metadata removed). A replay of the same `Idempotency-Key` answers `url` and `url_expires_at` as `null`; list the photos for a fresh URL. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `photos_locked`, `limit_reached` (all codes: Error codes below). #### Change kind or make primary `PATCH /v1/leads/{id}/photos/{photo}` · operationId `updatePhoto` Auth: API key with scope `photos:write` · account types: any. `kind`, or `is_primary: true` (the previous primary photo stops being primary). Only while the listing is not live (`409 photos_locked`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `photo` | path | string | required | Photo id (`photo_…`). | | `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. | Request body (`application/json`): `PhotoPatch` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Photo` | The photo. | Error statuses: 400, 401, 403, 404, 409, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `photos_locked` (all codes: Error codes below). #### Delete a photo `DELETE /v1/leads/{id}/photos/{photo}` · operationId `deletePhoto` Auth: API key with scope `photos:write` · account types: any. Removes the file, then the photo. If it was her primary photo, the oldest remaining one becomes primary. Only while the listing is not live (`409 photos_locked`). If the file cannot be removed, nothing changes and the answer is `502 upstream_failed` — retry. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `photo` | path | string | required | Photo id (`photo_…`). | Responses: | Status | Body | Meaning | |---|---|---| | 204 | — | Deleted. The answer has no body. | Error statuses: 401, 403, 404, 409, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `photos_locked`, `upstream_failed` (all codes: Error codes below). ### Earnings #### List your commissions `GET /v1/commissions` · operationId `listCommissions` Auth: API key with scope `earnings:read` · account types: any. Newest first. A commission is booked for your lead when her placement completes. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). | | `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. | | `ending_before` | query | string | optional | Id of the first item of the current page: the page before. | | `status` | query | string · one of `due`, `paid`, `void` | optional | Only this status. | | `created_since` | query | string (date-time) | optional | Booked at or after this instant (RFC 3339). | | `lead` | query | string | optional | Only the commissions of this lead (`lead_…`). | | `expand` | query | string | optional | `lead`: `lead` is a short lead object (`id`, `creator_name`, `creator_ref`, `stage`) instead of its id. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `CommissionList` | A page of commissions. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Get a commission `GET /v1/commissions/{id}` · operationId `getCommission` Auth: API key with scope `earnings:read` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Commission id (`com_…`). | | `expand` | query | string | optional | `lead`: `lead` is a short lead object (`id`, `creator_name`, `creator_ref`, `stage`) instead of its id. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Commission` | The commission. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Your payout details (masked) `GET /v1/payout-details` · operationId `getPayoutDetails` Auth: API key with scope `earnings:read` · account types: any. Method and a masked destination, never the full account data. Change them in the portal (Settings → Payout, needs your second factor); the API cannot. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `PayoutDetails` | Your payout details, masked. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". ### Keys #### List the keys of this mode `GET /v1/api-keys` · operationId `listApiKeys` Auth: API key with scope `keys:manage` · account types: any. Active keys of the calling key's mode (`live` or `test`), then the ones revoked in the last 90 days, on one page. Never a secret. No query parameters besides `fields`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ApiKeyList` | The keys of this mode. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Create a key `POST /v1/api-keys` · operationId `createApiKey` Auth: API key with scope `keys:manage` · account types: any. The new key has the calling key's mode and at most its scopes (more → `403 insufficient_scope`). So `keys:manage` and `webhooks:manage` reach a key made here only through a key that already has them, and those come from the portal with a second factor. The secret is in this answer only — store it now; a replay of the same `Idempotency-Key` answers `secret: null`. At most 10 active keys per mode (`409 limit_reached`); your key policy may cap `expires_at`. The new key inherits the calling key's restrictions: without `ip_allowlist` it gets the caller's; an `ip_allowlist` outside the caller's is `400 invalid_field`; it expires no later than the caller. A rolled key in its grace period cannot call this (`403 insufficient_scope`). A new live key needs the [API Terms](https://docs.creator-guard.com/authentication/#api-terms) and the data protection addendum (`403 terms_not_accepted` with `agreement_type: "api_terms"` or `"api_dpa"`); a test key does not. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `ApiKeyCreate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 201 | `ApiKey` | The key with its new secret — shown this once. A replay of the same `Idempotency-Key` answers `secret: null`. | Error statuses: 400, 401, 403, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_field`, `terms_not_accepted`, `insufficient_scope`, `limit_reached` (all codes: Error codes below). #### Revoke a key `DELETE /v1/api-keys/{id}` · operationId `revokeApiKey` Auth: API key with scope `keys:manage` · account types: any. Effective on the next request; repeating it is harmless. Only for keys whose scopes the calling key holds (else `403 insufficient_scope` naming the first missing one). The calling key itself only with `?force=true` (else `409 invalid_state` with `current_state: in_use`). Answers the revoked key. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Key id (`key_…`). | | `force` | query | boolean | optional | `true` to revoke the key that makes this request. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ApiKey` | The key (no secret). | Error statuses: 400, 401, 403, 404, 409, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `insufficient_scope`, `invalid_state` (all codes: Error codes below). #### Roll a key `POST /v1/api-keys/{id}/roll` · operationId `rollApiKey` Auth: API key with scope `keys:manage` · account types: any. A new key with the same label, scopes, IP allowlist and expiry; the old one keeps working for `grace_hours` (0–72, default 24; `0` revokes it now). Only for keys whose scopes the calling key holds. The new key also takes on the calling key's restrictions: IP allowlist = the overlap of the old key's and the caller's (none at all → `409 invalid_state` with `current_state: ip_allowlist_outside_caller`), expiry no later than the caller's. The new secret is in this answer only; a replay of the same `Idempotency-Key` answers `secret: null`. Rolling a live key needs the [API Terms](https://docs.creator-guard.com/authentication/#api-terms) and the data protection addendum (`403 terms_not_accepted` with `agreement_type: "api_terms"` or `"api_dpa"`); revoking never does. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Key id (`key_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `ApiKeyRoll` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ApiKey` | The key with its new secret — shown this once. A replay of the same `Idempotency-Key` answers `secret: null`. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `invalid_state` (all codes: Error codes below). ### Events #### List events `GET /v1/events` · operationId `listEvents` Auth: API key (any scopes) · account types: any. The last 30 days of this mode, newest first. Any key works; you only see events whose object the key may read (`leads:read` for lead, photo and confirmation events, `earnings:read` for commissions, … — see [Events](https://docs.creator-guard.com/events/)). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). | | `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. | | `ending_before` | query | string | optional | Id of the first item of the current page: the page before. | | `type` | query | string | optional | Exact type (`lead.updated`) or a group (`lead.*`). | | `created_after` | query | string (date-time) | optional | RFC 3339 timestamp; only events after it. | | `object` | query | string | optional | Events about one object: the id of a lead, photo, commission, API key or webhook endpoint (confirmation events carry the lead id). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `EventList` | A page of events. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Get an event `GET /v1/events/{id}` · operationId `getEvent` Auth: API key (any scopes) · account types: any. `404 not_found` for an unknown id, another account's event or one older than 30 days; `403 insufficient_scope` (with `error.scope`) when the key lacks the scope that reads the event's object. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Event id (`evt_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Event` | The event. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `insufficient_scope`, `not_found` (all codes: Error codes below). ### Webhooks #### List webhook endpoints `GET /v1/webhook-endpoints` · operationId `listWebhookEndpoints` Auth: API key with scope `webhooks:manage` · account types: any. The endpoints of this mode (at most 10, one page). Secrets are never listed. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `WebhookEndpointList` | The endpoints of this mode. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Create a webhook endpoint `POST /v1/webhook-endpoints` · operationId `createWebhookEndpoint` Auth: API key with scope `webhooks:manage` · account types: any. `https` only, port 443, a host that resolves to public addresses only; checked now and again before every delivery (a failed DNS lookup now → `502 upstream_failed`). At most 10 endpoints per mode (`409 limit_reached`). Every event type must be readable with this key's scopes (else `403 insufficient_scope` naming the scope); `["*"]` means every type this key can read, and the endpoint never carries more. The signing secret is in this answer only; a replay of the same `Idempotency-Key` answers `secret: null`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `WebhookEndpointCreate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 201 | `WebhookEndpoint` | The endpoint with its new signing secret — shown this once. A replay of the same `Idempotency-Key` answers `secret: null`. | Error statuses: 400, 401, 403, 409, 413, 415, 422, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `insufficient_scope`, `limit_reached`, `upstream_failed` (all codes: Error codes below). #### Get a webhook endpoint `GET /v1/webhook-endpoints/{id}` · operationId `getWebhookEndpoint` Auth: API key with scope `webhooks:manage` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Webhook endpoint id (`we_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `WebhookEndpoint` | The endpoint (no secret). | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Change a webhook endpoint `PATCH /v1/webhook-endpoints/{id}` · operationId `updateWebhookEndpoint` Auth: API key with scope `webhooks:manage` · account types: any. URL, event types, description, or `enabled` (re-enabling an endpoint disabled for failing starts its failure clock afresh). A new URL is checked like on create. New event types must be readable with this key's scopes (`403 insufficient_scope`); after a new URL or new event types the endpoint carries only what this key can read, and waiting deliveries it may no longer carry end `failed` (`scope_removed`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Webhook endpoint id (`we_…`). | | `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. | Request body (`application/json`): `WebhookEndpointUpdate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `WebhookEndpoint` | The endpoint (no secret). | Error statuses: 400, 401, 403, 404, 409, 412, 413, 415, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `insufficient_scope` (all codes: Error codes below). #### Delete a webhook endpoint `DELETE /v1/webhook-endpoints/{id}` · operationId `deleteWebhookEndpoint` Auth: API key with scope `webhooks:manage` · account types: any. The endpoint and its deliveries are removed; pending deliveries to it are dropped. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Webhook endpoint id (`we_…`). | Responses: | Status | Body | Meaning | |---|---|---| | 204 | — | Deleted. The answer has no body. | Error statuses: 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Roll the signing secret `POST /v1/webhook-endpoints/{id}/roll` · operationId `rotateWebhookSecret` Auth: API key with scope `webhooks:manage` · account types: any. A new signing secret, in this answer only (a replay of the same `Idempotency-Key` answers `secret: null`). For 24 hours every delivery is signed with both (two `v1=` values in `CG-Signature`). Only the newest two secrets sign: a second roll within the 24 hours retires the oldest at once. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Webhook endpoint id (`we_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `WebhookEndpoint` | The endpoint with its new signing secret — shown this once. A replay of the same `Idempotency-Key` answers `secret: null`. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Send a test event `POST /v1/webhook-endpoints/{id}/test` · operationId `testWebhookEndpoint` Auth: API key with scope `webhooks:manage` · account types: any. Queues a `ping` event for this endpoint only and answers its delivery (`202`); it is delivered and retried like every other event. Follow it in the deliveries list. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Webhook endpoint id (`we_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 202 | `WebhookDelivery` | The delivery, queued. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Re-send events of a time range `POST /v1/webhook-endpoints/{id}/replay` · operationId `replayWebhookEvents` Auth: API key with scope `webhooks:manage` · account types: any. Queues every event of the range that the endpoint subscribes to and may carry again (at most 30 days back). The endpoint holds at most 1,000 open deliveries afterwards; a range that does not fit is refused whole with `409 limit_reached` (`limit: 1000`), nothing queued. Deliveries are spread 250 ms apart and carry `replay: true`; receivers drop what they already have by `sequence`. At most 10 replays per account and day (test mode: 5) → `429 rate_limited`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Webhook endpoint id (`we_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `WebhookReplay` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 202 | `ReplayResult` | How many deliveries were queued. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `rate_limited`, `limit_reached` (all codes: Error codes below). #### Deliveries to an endpoint `GET /v1/webhook-endpoints/{id}/deliveries` · operationId `listWebhookDeliveries` Auth: API key with scope `webhooks:manage` · account types: any. Newest first, 30 days, each with every attempt (status code, duration, error). Pages forward only: `starting_after`, no `ending_before`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Webhook endpoint id (`we_…`). | | `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). | | `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `WebhookDeliveryList` | A page of deliveries. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Retry a delivery now `POST /v1/webhook-endpoints/{id}/deliveries/{d}/retry` · operationId `retryWebhookDelivery` Auth: API key with scope `webhooks:manage` · account types: any. Also for a delivery that has already `failed`: it is due again now (`202`), its attempt count is kept. A delivery of an event the endpoint may no longer carry (its object type left the endpoint's scope) is refused with `409 invalid_state` (`current_state: scope_removed`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Webhook endpoint id (`we_…`). | | `d` | path | string | required | Delivery id (`whd_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 202 | `WebhookDelivery` | The delivery, queued. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_state` (all codes: Error codes below). ### OAuth apps #### List OAuth apps `GET /v1/oauth-apps` · operationId `listOAuthApps` Auth: API key with scope `oauth_apps:manage` · account types: any. The OAuth apps of this mode (at most 10, one page). Client secrets are never listed. No query parameters besides `fields`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `OAuthAppList` | The OAuth apps of this mode. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Register an OAuth app `POST /v1/oauth-apps` · operationId `createOAuthApp` Auth: API key with scope `oauth_apps:manage` · account types: any. An app that creators sign in to with Creator Guard (OAuth 2.1, authorization code with PKCE). Redirect URIs are matched exactly; `https` only, no private or loopback hosts (`http://localhost` and `127.0.0.1` with a port only for apps of test keys). A confidential app gets a `client_secret`, in this answer only — a replay of the same `Idempotency-Key` answers `client_secret: null`. At most 10 apps per mode (`409 invalid_state` with `current_state: app_limit_reached`). Registering a live app needs the [API Terms](https://docs.creator-guard.com/authentication/#api-terms) and the data protection addendum (`403 terms_not_accepted` with `agreement_type: "api_terms"` or `"api_dpa"`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `OAuthAppCreate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 201 | `OAuthApp` | The OAuth app with its new client secret (confidential apps) — shown this once. A replay of the same `Idempotency-Key` answers `client_secret: null`. | Error statuses: 400, 401, 403, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `invalid_state` (all codes: Error codes below). #### Get an OAuth app `GET /v1/oauth-apps/{id}` · operationId `getOAuthApp` Auth: API key with scope `oauth_apps:manage` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | OAuth app id (`app_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `OAuthApp` | The OAuth app (no client secret). | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Change an OAuth app `PATCH /v1/oauth-apps/{id}` · operationId `updateOAuthApp` Auth: API key with scope `oauth_apps:manage` · account types: any. Name, logo, privacy URL, redirect URIs or scopes. Narrowing the scopes narrows the creators' existing grants too. `confidential` cannot change (`400 invalid_field`; register a new app instead). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | OAuth app id (`app_…`). | | `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. | Request body (`application/json`): `OAuthAppUpdate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `OAuthApp` | The OAuth app (no client secret). | Error statuses: 400, 401, 403, 404, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_field` (all codes: Error codes below). #### Delete an OAuth app `DELETE /v1/oauth-apps/{id}` · operationId `deleteOAuthApp` Auth: API key with scope `oauth_apps:manage` · account types: any. Every creator's grant to the app is revoked first: its access and refresh tokens stop working at once. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | OAuth app id (`app_…`). | Responses: | Status | Body | Meaning | |---|---|---| | 204 | — | Deleted. The answer has no body. | Error statuses: 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Roll the client secret `POST /v1/oauth-apps/{id}/roll` · operationId `rollOAuthAppSecret` Auth: API key with scope `oauth_apps:manage` · account types: any. A new client secret for a confidential app, in this answer only (a replay of the same `Idempotency-Key` answers `client_secret: null`). The previous secret keeps working for 24 hours; a second roll within them ends it at once. A public app has no secret (`409 invalid_state` with `current_state: public_client`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | OAuth app id (`app_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `OAuthApp` | The OAuth app with its new client secret (confidential apps) — shown this once. A replay of the same `Idempotency-Key` answers `client_secret: null`. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_state` (all codes: Error codes below). ### Members #### People and open invitations `GET /v1/members` · operationId `listMembers` Auth: API key with scope `members:manage` · account types: any. Everyone who can sign in to the account (`status: active`, id `mem_…`, the owner first) and every open, unexpired invitation (`status: invited`, id `inv_…`). Not paginated. Live keys only: a `cg_test_` key gets `404 not_found`, because test mode has no logins. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `MemberList` | People (owner first) and open invitations. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `not_found` (all codes: Error codes below). #### Invite a person by email `POST /v1/members` · operationId `inviteMember` Auth: API key with scope `members:manage` · account types: any. Creates an invitation for `developer` or `viewer` (admins are invited in the portal by an owner or admin with two-factor authentication) and returns it once with `join_url` (valid 48 hours). Send the link yourself, only through a channel the person controls — Creator Guard sends no email, and whoever opens the link first sets the password for this address. On the join page the person sets a password for exactly this email address (or signs in, if a login with it exists) and accepts. A replay of the same `Idempotency-Key` answers `join_url: null` — the link is never stored. Inviting an address again replaces its open invitation (the old link stops working). A person who already is a member → `409 invalid_state` with `current_state: active`. An address whose login cannot join any account (it belongs to another account, a creator or Creator Guard staff) gets the same `201` invitation as any address, with the same join page; it can never be accepted. At most 20 invitations per account in 24 hours, those included → `409 limit_reached` with `limit: 20`. Works before the terms are accepted. Live keys only. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `MemberInvite` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 201 | `Member` | The invitation with `join_url` — shown this once. A replay of the same `Idempotency-Key` answers `join_url: null`. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_state`, `limit_reached` (all codes: Error codes below). #### Remove a person or revoke an invitation `DELETE /v1/members/{id}` · operationId `deleteMember` Auth: API key with scope `members:manage` · account types: any. `mem_…` removes the person from the account in one step: their login acts for no account from its next request on, their open invitations are revoked, every API key whose secret they had is revoked (keys they created in the portal and keys those keys created), and webhook endpoints whose signing secret they know get a new secret nobody has seen and are disabled until an owner or admin rolls the secret and enables them again. A login that was created through a join link is deleted with its last membership. `inv_…` revokes an open invitation; its link stops working. The owner cannot be removed: `409 invalid_state` with `current_state: owner`. Works before the terms are accepted. Live keys only. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Member id (`mem_…`) or invitation id (`inv_…`). | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `MemberDeleted` | The person was removed or the invitation revoked. | Error statuses: 400, 401, 403, 404, 409, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_state` (all codes: Error codes below). ### Creator #### Get the creator `GET /v1/creator/me` · operationId `getCreatorMe` Auth: creator access token (OAuth) with scope `creator.profile:read` · account types: any. Her name, stage and next steps and, once an agency paid for her, that agency. All `/v1/creator/…` endpoints take a creator's OAuth access token (`cgo_live_…`) and act for her alone; an account API key is `403 wrong_account_type`. A grant whose app owner no longer submitted her, or whose reservation ended, stops working (`401 invalid_token`); an app owner that is not approved gets `403 account_not_active`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Creator` | Her creator object. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_token`, `account_not_active`, `wrong_account_type` (all codes: Error codes below). #### Get her profile `GET /v1/creator/profile` · operationId `getCreatorProfile` Auth: creator access token (OAuth) with scope `creator.profile:read` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `CreatorProfile` | Her profile. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Change her profile `PATCH /v1/creator/profile` · operationId `updateCreatorProfile` Auth: creator access token (OAuth) with scope `creator.profile:write` · account types: any. `lead` (contact fields) while her lead is `submitted`, else `409 lead_locked`; `listing` until the listing is live, else `409 listing_locked`. Every problem of the body comes back at once (`400`, `error.details`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. | Request body (`application/json`): `CreatorProfilePatch` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `CreatorProfile` | Her profile. | Error statuses: 400, 401, 403, 409, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `lead_locked`, `listing_locked` (all codes: Error codes below). #### Submit her listing for review `POST /v1/creator/submit-for-review` · operationId `submitCreatorForReview` Auth: creator access token (OAuth) with scope `creator.profile:write` · account types: any. Same rules as for the partner: `422 not_ready_for_review` with `blockers` while something is missing. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Creator` | Her creator object. | Error statuses: 400, 401, 403, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `not_ready_for_review` (all codes: Error codes below). #### List her photos `GET /v1/creator/photos` · operationId `listCreatorPhotos` Auth: creator access token (OAuth) with scope `creator.photos:write` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `CreatorPhotoList` | Her photos, primary first, each with a URL signed for 1 hour. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Upload a photo `POST /v1/creator/photos` · operationId `uploadCreatorPhoto` Auth: creator access token (OAuth) with scope `creator.photos:write` · account types: any. Multipart, like a partner upload: the image is re-encoded on our side and every metadata (EXIF, GPS) removed before it is stored; the file name is never used. `409 photos_locked` once her listing is live; at most 20 photos. A repeated `Idempotency-Key` replays the first answer (with `url: null`) even with another file. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`multipart/form-data`): `PhotoUpload` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 201 | `CreatorPhoto` | The photo was stored (re-encoded, metadata removed). A replay of the same `Idempotency-Key` answers `url` and `url_expires_at` as `null`; list her photos for a fresh URL. | Error statuses: 400, 401, 403, 409, 413, 415, 422, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `photos_locked` (all codes: Error codes below). #### Delete a photo `DELETE /v1/creator/photos/{photo}` · operationId `deleteCreatorPhoto` Auth: creator access token (OAuth) with scope `creator.photos:write` · account types: any. The photo is removed, then its file (`502 upstream_failed`: the photo is put back, nothing changed). `409 photos_locked` once live. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `photo` | path | string | required | Photo id (`photo_…`). | Responses: | Status | Body | Meaning | |---|---|---| | 204 | — | Deleted. The answer has no body. | Error statuses: 401, 403, 404, 409, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `photos_locked`, `upstream_failed` (all codes: Error codes below). #### Get a consent text `GET /v1/creator/consent-text` · operationId `getConsentText` Auth: creator access token (OAuth) with scope `creator.profile:read` · account types: any. The current text of `kind` that your app must show her in full before it sends her decision, and the `version` to send with it. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `kind` | query | string · one of `consent`, `age_confirmation`, `creator_terms` | required | `consent`, `age_confirmation` or `creator_terms`. | | `locale` | query | string · pattern `^[a-z]{2}$` | optional | Two lowercase letters, default `en`; a language without its own text falls back to English. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ConsentText` | The current published text of that kind and language. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Get her consent state `GET /v1/creator/consent` · operationId `getCreatorConsent` Auth: creator access token (OAuth) with scope `creator.profile:read` · account types: any. Consent and 18+ state with every entry of her consent ledger (never her IP address or browser). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `CreatorConsentState` | Her consent and 18+ state with her ledger entries. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Record her consent `POST /v1/creator/consent/grant` · operationId `grantCreatorConsent` Auth: creator access token (OAuth) with scope `creator.consent:write` · account types: any. A ledger entry with channel `oauth_app:app_…`, the text version she saw and the IP and user agent of your request (your server). Only the current version (`409 consent_text_outdated` with `current_version`). The consent text includes her 18+ confirmation: unless 18+ is already confirmed, the grant also records `age_confirmed` on the same text, like the hosted consent page. While her 18+ check is declined or under document review the grant is `409 invalid_state` (`current_state` `age_declined` or `age_pending`) and records nothing. An app owned by the account that referred her → `403 referrer_app_not_allowed` (she consents on Creator Guard: consent link or creator portal). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `ConsentDecision` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `CreatorConsentState` | Her consent and 18+ state with her ledger entries. | Error statuses: 400, 401, 403, 409, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `referrer_app_not_allowed`, `invalid_state`, `consent_text_outdated` (all codes: Error codes below). #### Record her withdrawal `POST /v1/creator/consent/revoke` · operationId `revokeCreatorConsent` Auth: creator access token (OAuth) with scope `creator.consent:write` · account types: any. Her photos stop being released. Never refused because of the text version; send the one she saw if you have it. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `ConsentDecision` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `CreatorConsentState` | Her consent and 18+ state with her ledger entries. | Error statuses: 400, 401, 403, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Record her 18+ confirmation `POST /v1/creator/age-confirmation` · operationId `confirmCreatorAge` Auth: creator access token (OAuth) with scope `creator.consent:write` · account types: any. Only the current text version. Declined or under document review → `409 invalid_state`; already confirmed → unchanged. An app owned by the account that referred her → `403 referrer_app_not_allowed`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `ConsentDecision` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `CreatorConsentState` | Her consent and 18+ state with her ledger entries. | Error statuses: 400, 401, 403, 409, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `referrer_app_not_allowed`, `invalid_state` (all codes: Error codes below). #### List her agreements `GET /v1/creator/agreements` · operationId `listCreatorAgreements` Auth: creator access token (OAuth) with scope `creator.consent:write` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `CreatorAgreementList` | Her agreements (the creator terms). | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Record her acceptance of the creator terms `POST /v1/creator/agreements/{type}/accept` · operationId `acceptCreatorTerms` Auth: creator access token (OAuth) with scope `creator.consent:write` · account types: any. Only `creator_terms`, only the current version (`409 consent_text_outdated`). An app owned by the account that referred her → `403 referrer_app_not_allowed`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `type` | path | string | required | Always `creator_terms`; any other value is `404`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `CreatorTermsAccept` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `CreatorAgreement` | The agreement with her acceptance. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `referrer_app_not_allowed`, `consent_text_outdated` (all codes: Error codes below). #### List her support tickets `GET /v1/creator/support-tickets` · operationId `listCreatorTickets` Auth: creator access token (OAuth) with scope `creator.support` · account types: any. Newest first; pages forward only (`starting_after`; `ending_before` is `400 invalid_field`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). | | `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `SupportTicketList` | Her support tickets, newest first. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_field` (all codes: Error codes below). #### Open a support ticket `POST /v1/creator/support-tickets` · operationId `createCreatorTicket` Auth: creator access token (OAuth) with scope `creator.support` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `SupportTicketCreate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 201 | `SupportTicket` | The support ticket. | Error statuses: 400, 401, 403, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### List the messages of a ticket `GET /v1/creator/support-tickets/{id}/messages` · operationId `listCreatorTicketMessages` Auth: creator access token (OAuth) with scope `creator.support` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Support ticket id (`tkt_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `SupportMessageList` | Every message of the ticket, oldest first. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Reply to a ticket `POST /v1/creator/support-tickets/{id}/messages` · operationId `replyCreatorTicket` Auth: creator access token (OAuth) with scope `creator.support` · account types: any. A closed ticket → `409 invalid_state`; open a new one. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Support ticket id (`tkt_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `SupportReply` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 201 | `SupportMessage` | Her new message. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_state` (all codes: Error codes below). #### Close a ticket `POST /v1/creator/support-tickets/{id}/close` · operationId `closeCreatorTicket` Auth: creator access token (OAuth) with scope `creator.support` · account types: any. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Support ticket id (`tkt_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `SupportTicket` | The support ticket. | Error statuses: 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Request her data export `POST /v1/creator/data-export` · operationId `requestCreatorDataExport` Auth: creator access token (OAuth) with scope `creator.privacy` · account types: any. Everything we hold about her that she may see, as one JSON file (her GDPR rights of access and portability). Answers `202` with a job (`Location: /v1/jobs/job_…`); when it succeeded, `GET /v1/creator/data-export/{id}` with `result.data_request` gives a download link; the file is kept for 7 days. One export per app per 24 hours: asking again answers your app's open or recent job. The export belongs to the app that asked: another of her apps gets `404 not_found` for it and asks for its own. The file includes her support conversations with us. The app owner also receives `data_export.ready` and `job.completed`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 202 | `Job` | The export job (new, or the open/recent one of the last 24 hours). Poll `Location` until `status` is `succeeded` or `failed`. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `not_found` (all codes: Error codes below). #### Get her data export `GET /v1/creator/data-export/{id}` · operationId `getCreatorDataExport` Auth: creator access token (OAuth) with scope `creator.privacy` · account types: any. With `download_url` while `status` is `ready`: a fresh link on every call, valid for 1 hour at most and never past `expires_at`. Download right away; call again for a new link. Only the app that requested the export may read it (another of her apps: `404 not_found`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Data request id (`dreq_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `DataRequest` | The data request. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `not_found` (all codes: Error codes below). #### Request the deletion of her data `POST /v1/creator/deletion-request` · operationId `requestCreatorDeletion` Auth: creator access token (OAuth) with scope `creator.privacy` · account types: any. Creates her deletion request (or answers the open one). Creator Guard checks and completes it: her personal data, photos, login and grants are deleted; your account receives `deletion_request.completed`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 202 | `DataRequest` | Her deletion request (new, or the open one). Creator Guard handles it; the app owner receives `deletion_request.completed` when it is done. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Your app's connection `GET /v1/creator/connected-apps` · operationId `listCreatorConnectedApps` Auth: creator access token (OAuth) with scope `creator.profile:read` · account types: any. Your own active grant for her (a list of at most one entry). Her other connected apps are never shown to an app: she sees and manages the full list in the hosted creator portal. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ConnectedAppList` | The apps she authorised and has not revoked. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Disconnect your app `DELETE /v1/creator/connected-apps/{app}` · operationId `revokeCreatorConnectedApp` Auth: creator access token (OAuth) with scope `creator.profile:write` · account types: any. Revokes her grant of the calling app (pass your own app id), which ends this token and its refresh token. Any other app id is `404 not_found`: an app can never revoke her other connections; she does that in the hosted creator portal. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `app` | path | string | required | Id of a connected OAuth app (`app_…`). | Responses: | Status | Body | Meaning | |---|---|---| | 204 | — | Deleted. The answer has no body. | Error statuses: 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `not_found` (all codes: Error codes below). ### Jobs #### Get a job `GET /v1/jobs/{id}` · operationId `getJob` Auth: API key (any scopes) or creator access token (OAuth) (any scopes) · account types: any. An asynchronous job. A `data_export` job needs a creator access token with `creator.privacy` (`403 insufficient_scope` otherwise) of the app that started it (another of her apps: `404`); no job type can be read with an account API key yet (`404`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Job id (`job_…`). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Job` | The job. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `insufficient_scope` (all codes: Error codes below). ### Usage & audit #### Your request log `GET /v1/request-logs` · operationId `listRequestLogs` Auth: API key with scope `account:read` · account types: any. The last 30 days of this mode, newest first. Method, route template, status, error code, key and duration — never bodies. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). | | `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. | | `ending_before` | query | string | optional | Id of the first item of the current page: the page before. | | `status` | query | integer · 100–599 | optional | HTTP status, e.g. `429`. | | `route` | query | string | optional | Route template as logged, e.g. `/v1/leads/{id}`. | | `key` | query | string | optional | Only requests of this key (`key_…`). | | `created_since` | query | string (date-time) | optional | RFC 3339 timestamp; only requests from then on. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `RequestLogList` | A page of your request log. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Usage statistics `GET /v1/usage` · operationId `getUsage` Auth: API key with scope `usage:read` · account types: any. Requests, errors by code and p50/p95 latency per UTC day, per route and per key, for this mode. Without `from` and `to` you get the last 30 days up to today; a range spans at most 90 days. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `from` | query | string (date) | optional | First day (UTC), `YYYY-MM-DD`; default 29 days before `to`. | | `to` | query | string (date) | optional | Last day (UTC), inclusive; default today. | | `granularity` | query | string | optional | `day` (the only value today). | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Usage` | Usage statistics. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". #### Audit trail of your account `GET /v1/audit-events` · operationId `listAuditEvents` Auth: API key with scope `audit:read` · account types: any. Key, webhook and key-policy changes, account changes made with the API, test-data resets and limits changed by Creator Guard — who, when, from which IP. 90 days, newest first, in the key's mode: a live key also sees account-wide changes (`mode: null`), a test key only test-mode ones. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). | | `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. | | `ending_before` | query | string | optional | Id of the first item of the current page: the page before. | | `action` | query | string | optional | e.g. `api_key.created`. | | `created_since` | query | string (date-time) | optional | RFC 3339 timestamp; only changes from then on. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `AuditEventList` | A page of audit events. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". ### Agency #### Get your search profile `GET /v1/search-profile` · operationId `getSearchProfile` Auth: API key with scope `offers:read` · account types: agency. What we match creators against before we offer them to you. Agency keys only (`403 wrong_account_type` otherwise). Before your first `PUT` you get the defaults (`updated_at: null`, no `ETag`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `SearchProfile` | Your search profile. `ETag` only once you saved one. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type` (all codes: Error codes below). #### Replace your search profile `PUT /v1/search-profile` · operationId `replaceSearchProfile` Auth: API key with scope `search_profile:write` · account types: agency. **Full replacement:** a field you leave out goes back to its default (`[]`, `null`, `creator_stage: "both"`, the portal `flex`) — read it, change what you need, send the whole object back. `flex` takes only the portal's preset levels (`400 invalid_field` with `field: "flex."`). Money is US dollars only. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. | Request body (`application/json`): `SearchProfilePut` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `SearchProfile` | Your search profile. `ETag` only once you saved one. | Error statuses: 400, 401, 403, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_field`, `terms_not_accepted`, `wrong_account_type` (all codes: Error codes below). #### Get your agency profile `GET /v1/agency-profile` · operationId `getAgencyProfile` Auth: API key with scope `account:read` · account types: agency. Your agency's public facts. `tier` and `verified_revenue` are set by Creator Guard. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `AgencyProfile` | Your agency profile. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type` (all codes: Error codes below). #### Update your agency profile `PATCH /v1/agency-profile` · operationId `updateAgencyProfile` Auth: API key with scope `account:write` · account types: agency. Only the fields you send change; `null` clears one. `tier` and `verified_revenue` cannot be sent (`400 unknown_field`); `monthly_revenue` is whole US dollars. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. | Request body (`application/json`): `AgencyProfilePatch` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `AgencyProfile` | Your agency profile. | Error statuses: 400, 401, 403, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `unknown_field`, `terms_not_accepted`, `wrong_account_type` (all codes: Error codes below). ### Offers #### List your offers `GET /v1/offers` · operationId `listOffers` Auth: API key with scope `offers:read` · account types: agency. Newest first. `status` is the public status: an open offer whose deadline passed reads `expired` even before our hourly job closes it. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). | | `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. | | `ending_before` | query | string | optional | Id of the first item of the current page: the page before. | | `status` | query | string · one of `offered`, `accepted`, `declined`, `expired`, `retracted`, `contacted`, `in_talks`, `signed`, `lost` | optional | Only offers with this status (an open offer past its deadline counts as `expired`). | | `created_since` | query | string (date-time) | optional | RFC 3339 timestamp; only items created from then on. | | `updated_since` | query | string (date-time) | optional | RFC 3339 timestamp; only items changed from then on. | | `expires_before` | query | string (date-time) | optional | RFC 3339 timestamp; only offers whose deadline is before it. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `OfferList` | A page of offers. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type` (all codes: Error codes below). #### Get an offer `GET /v1/offers/{id}` · operationId `getOffer` Auth: API key with scope `offers:read` · account types: agency. The offer, the creator's listing while you may see it (open or accepted offers and later; `null` once declined, expired or retracted), your reservation, `next_actions` and `match` against your search profile. Never her contact details, the referrer or internal notes — the contact comes with `GET /v1/reservations/{id}/creator` after payment. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Offer` | The offer. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type` (all codes: Error codes below). #### Set your note on an offer `PATCH /v1/offers/{id}` · operationId `updateOffer` Auth: API key with scope `offers:write` · account types: agency. `agency_note` (1–500 characters after trimming, `null` clears it). Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. | | `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. | Request body (`application/json`): `OfferPatch` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Offer` | The offer. | Error statuses: 400, 401, 403, 404, 409, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `wrong_account_type` (all codes: Error codes below). #### List the creator's photos `GET /v1/offers/{id}/photos` · operationId `listOfferPhotos` Auth: API key with scope `offers:read` · account types: agency. Only photos she agreed to share, as signed links valid for one hour, on one page. Only while the listing is visible to you; otherwise `409 invalid_state` with `error.current_state`. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `OfferPhotoList` | The photos she agreed to share, as signed links valid for one hour. | Error statuses: 400, 401, 403, 404, 409, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type`, `invalid_state` (all codes: Error codes below). #### Accept an offer `POST /v1/offers/{id}/accept` · operationId `acceptOffer` Auth: API key with scope `offers:write` · account types: agency. Reserves the creator for you and creates the reservation (`reservation`, status `awaiting_payment`). Needs the current `agency_terms` **and** the current `warranty_terms` — otherwise `403 terms_not_accepted` with `error.agreement_type` and nothing changes. `409 offer_taken` (another agency accepted first), `409 offer_expired` (deadline passed), `409 listing_unavailable` (listing pulled or offer retracted), `409 invalid_state` (not open). No request fields. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Offer` | The offer. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `invalid_state`, `offer_taken`, `offer_expired`, `listing_unavailable` (all codes: Error codes below). #### Decline an offer `POST /v1/offers/{id}/decline` · operationId `declineOffer` Auth: API key with scope `offers:write` · account types: agency. `note` (50–500 characters after trimming) tells us why. Only open offers (`409 invalid_state`); a passed deadline is `409 offer_expired`. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `OfferDecline` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Offer` | The offer. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `invalid_state`, `offer_expired` (all codes: Error codes below). #### Undo an accept `POST /v1/offers/{id}/undo-accept` · operationId `undoAcceptOffer` Auth: API key with scope `offers:write` · account types: agency. Until `undo_until` (`GET /v1/settings` → `accept_undo_minutes`) and while the reservation is unpaid, the offer goes back to `offered` and the reservation is cancelled. Later: `409 undo_window_passed`; not accepted or already paid: `409 invalid_state`. No request fields. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Offer` | The offer. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `invalid_state`, `undo_window_passed` (all codes: Error codes below). #### Mark the creator as contacted `POST /v1/offers/{id}/mark-contacted` · operationId `markOfferContacted` Auth: API key with scope `offers:write` · account types: agency. From `accepted`, once your reservation is paid (`409 payment_pending` before). No request fields. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Offer` | The offer. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `payment_pending` (all codes: Error codes below). #### Mark talks as started `POST /v1/offers/{id}/mark-in-talks` · operationId `markOfferInTalks` Auth: API key with scope `offers:write` · account types: agency. From `contacted` (`409 invalid_state` otherwise). No request fields. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Offer` | The offer. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `invalid_state` (all codes: Error codes below). #### Mark the creator as signed `POST /v1/offers/{id}/mark-signed` · operationId `markOfferSigned` Auth: API key with scope `offers:write` · account types: agency. From `contacted` or `in_talks`, or from `accepted` once the reservation is paid (`409 payment_pending` before). No request fields. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Offer` | The offer. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `payment_pending` (all codes: Error codes below). #### Mark the placement as lost `POST /v1/offers/{id}/mark-lost` · operationId `markOfferLost` Auth: API key with scope `offers:write` · account types: agency. Only from `accepted`, before the placement fee was received, with an `outcome_reason`. Once the fee was received the deal can no longer be marked lost (`409 deal_paid`): file a warranty claim (`POST /v1/reservations/{id}/warranty-claim`) instead. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `OfferMarkLost` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Offer` | The offer. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `deal_paid` (all codes: Error codes below). ### Reservations #### List your reservations `GET /v1/reservations` · operationId `listReservations` Auth: API key with scope `reservations:read` · account types: agency. Newest first. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). | | `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. | | `ending_before` | query | string | optional | Id of the first item of the current page: the page before. | | `status` | query | string · one of `awaiting_payment`, `paid`, `completed`, `refunded`, `cancelled` | optional | Only reservations with this status. | | `created_since` | query | string (date-time) | optional | RFC 3339 timestamp; only items created from then on. | | `updated_since` | query | string (date-time) | optional | RFC 3339 timestamp; only items changed from then on. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ReservationList` | A page of reservations. | Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type` (all codes: Error codes below). #### Get a reservation `GET /v1/reservations/{id}` · operationId `getReservation` Auth: API key with scope `reservations:read` · account types: agency. Amount, payment reference and due date, payment and warranty dates, your warranty claim. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Reservation` | The reservation. | Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type` (all codes: Error codes below). #### File a warranty claim `POST /v1/reservations/{id}/warranty-claim` · operationId `fileWarrantyClaim` Auth: API key with scope `reservations:write` · account types: agency. Once per reservation, while it is paid and the warranty runs. `409 claim_exists` (already filed), `409 payment_pending` (not paid yet), `409 warranty_expired` (warranty over or completed), `409 invalid_state` (refunded or cancelled). Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `WarrantyClaimCreate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Reservation` | The reservation. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `invalid_state`, `payment_pending`, `claim_exists`, `warranty_expired` (all codes: Error codes below). #### Get the creator's contact `GET /v1/reservations/{id}/creator` · operationId `getReservationCreator` Auth: API key with scope `reservations:read` · account types: agency. After payment only (`paid` or `completed`): name, Instagram, other contact, platforms, followers, niche and creator number. Never the referrer or internal notes. Unpaid: `409 payment_pending`; refunded or cancelled: `409 invalid_state`. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. | | `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ReservationCreator` | The creator's contact. | Error statuses: 400, 401, 403, 404, 409, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type`, `invalid_state`, `payment_pending` (all codes: Error codes below). ### Test mode #### Confirm consent and 18+ (test mode) `POST /v1/test-helpers/leads/{id}/confirm` · operationId `testConfirmLead` Auth: API key with scope `leads:write` · account types: any. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Records consent and the 18+ confirmation as if she had used her link. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Lead` | The lead. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `not_found` (all codes: Error codes below). #### Approve the listing (test mode) `POST /v1/test-helpers/leads/{id}/approve-listing` · operationId `testApproveListing` Auth: API key with scope `leads:write` · account types: any. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Plays our review: a listing in review goes live. Missing consent, 18+ confirmation or fee → `422 not_ready_for_review`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Lead` | The lead. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `not_found`, `not_ready_for_review` (all codes: Error codes below). #### Reject a lead (test mode) `POST /v1/test-helpers/leads/{id}/reject` · operationId `testRejectLead` Auth: API key with scope `leads:write` · account types: any. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Plays our review: the lead becomes `rejected` with your `outcome_reason`. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Lead id (`lead_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `TestLeadReject` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Lead` | The lead. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `not_found` (all codes: Error codes below). #### Pay a commission (test mode) `POST /v1/test-helpers/commissions/{id}/mark-paid` · operationId `testMarkCommissionPaid` Auth: API key with scope `leads:write` · account types: any. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. A `due` commission becomes `paid` (any other → `409 invalid_state`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Commission id (`com_…`). | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Commission` | The commission. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `not_found`, `invalid_state` (all codes: Error codes below). #### Delete all test data (test mode) `POST /v1/test-helpers/reset` · operationId `testReset` Auth: API key with scope `keys:manage` · account types: any. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Deletes every lead, photo, commission, event, delivery, sandbox file and stored `Idempotency-Key` answer of your account in the sandbox. Your keys, webhook endpoints and accepted terms stay. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `TestReset` | What was deleted from the sandbox. | Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `not_found` (all codes: Error codes below). #### A sandbox photo or logo `GET /v1/test-files/{path}` · operationId `getTestFile` Auth: none (no API key needed). Photo and logo URLs of test mode point here; use them exactly as given. No key needed: the URL carries a signed `token` that expires like every photo URL (1 hour). `{path}` is `//` and contains slashes, so your request log shows this route as `/v1/test-files/{bucket}/{path}`. Requests without a key share a per-IP budget (`429 rate_limited`). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `path` | path | string | required | Bucket and object path as in the URL we gave you; contains slashes. | | `token` | query | string | required | Signed token from the URL we gave you. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | — | The file. | Error statuses: 400, 404, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `rate_limited` (all codes: Error codes below). #### Create a test offer (test mode) `POST /v1/test-helpers/offers` · operationId `testCreateOffer` Auth: API key with scope `offers:write` · account types: agency. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Creates a synthetic creator of a fixed sandbox referrer and offers her to your agency, as our matching would. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `TestOfferCreate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 201 | `Offer` | The new test offer. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type`, `not_found` (all codes: Error codes below). #### Mark a reservation as paid (test mode) `POST /v1/test-helpers/reservations/{id}/mark-paid` · operationId `testMarkReservationPaid` Auth: API key with scope `reservations:write` · account types: agency. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Plays our bookkeeping when your transfer arrives: `awaiting_payment` → `paid` (her contact is unlocked, the warranty starts). No request fields. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Reservation` | The reservation. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type`, `not_found` (all codes: Error codes below). #### Complete a reservation (test mode) `POST /v1/test-helpers/reservations/{id}/complete` · operationId `testCompleteReservation` Auth: API key with scope `reservations:write` · account types: agency. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Ends the warranty early: `paid` → `completed`. No request fields. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Reservation` | The reservation. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type`, `not_found` (all codes: Error codes below). #### Refund a reservation (test mode) `POST /v1/test-helpers/reservations/{id}/refund` · operationId `testRefundReservation` Auth: API key with scope `reservations:write` · account types: agency. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Plays an accepted warranty claim: `paid` → `refunded`. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. | | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `TestReservationRefund` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `Reservation` | The reservation. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type`, `not_found` (all codes: Error codes below). #### Advance the test clock (test mode) `POST /v1/test-helpers/clock/advance` · operationId `testAdvanceClock` Auth: API key with scope `offers:write` · account types: agency. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Moves the deadlines of your test offers and reservations `hours` (1–720) into the past and runs our expiry jobs: open offers expire, unpaid reservations are cancelled, warranties complete — with the same events. Agency keys only (`403 wrong_account_type` otherwise). Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. | Request body (`application/json`): `ClockAdvance` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 200 | `ClockAdvanceResult` | What the expiry jobs changed in your sandbox. | Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `wrong_account_type`, `not_found` (all codes: Error codes below). #### Create an authorization code (test mode) `POST /v1/test-helpers/oauth-codes` · operationId `testOAuthCode` Auth: API key with scope `oauth_apps:manage` · account types: any. Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. The hosted sign-in page `/oauth/authorize` serves live apps only (the sandbox has no real creator logins), so a test-mode app (`cgcl_test_…`) gets its authorization codes here, exactly as if the creator of the lead had clicked "Allow": the answer's `code` is valid for 60 seconds and one exchange at the normal `/oauth/token`, together with the `code_verifier` behind `code_challenge` (S256). The lead must be one your account may connect (you submitted it, or you hold a paid reservation for it), otherwise `404 not_found`. `redirect_uri` and every scope must be registered for the app (`400 invalid_field`). A code is a single-use secret, so an `Idempotency-Key` is ignored and a retry creates a new code. `503 not_configured` while OAuth is switched off on our side. Parameters: | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string | optional | Ignored on this endpoint: a code is single-use, a retry creates a new one. | Request body (`application/json`): `OAuthTestCodeCreate` — fields under Schemas. Responses: | Status | Body | Meaning | |---|---|---| | 201 | `OAuthTestCode` | A test-mode authorization code, shown this once: valid for 60 seconds and one exchange at `/oauth/token`. | Error statuses: 400, 401, 403, 404, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status". Error codes named for this operation: `invalid_field`, `not_found`, `not_configured` (all codes: Error codes below). ### Response headers | Header | Type | Sent | Description | |---|---|---|---| | `X-Request-Id` | string · pattern `^req_[a-z2-7]{26}$` | always | Id of this request (`req_…`), also `error.request_id`. Quote it to support. | | `X-API-Version` | string · pattern `^1\.[0-9]+\.[0-9]+$` | always | The contract version that answered (`info.version`). Log it with your requests. | | `RateLimit-Policy` | string | when it applies | The limits that apply to this key, e.g. `100;w=60, 10000;w=86400`. | | `RateLimit` | string | when it applies | State of the tightest window: `limit=100, remaining=97, reset=42` (seconds). | | `Retry-After` | integer | when it applies | Seconds to wait before the next attempt, computed from the window that is used up. | | `ETag` | string | when it applies | Version of the resource; send it back in `If-Match` to make a change race-safe. | | `Idempotent-Replayed` | string | when it applies | `true` when this is the stored answer to an earlier request with the same `Idempotency-Key`. | ### Error responses by status | Status | Codes and meaning | |---|---| | 400 | The body, a field or a query parameter is invalid: `invalid_json`, `invalid_body`, `unknown_field`, `unknown_parameter`, `missing_field`, `invalid_field`, `missing_contact`, `age_below_18`, `consent_required`, `invalid_cursor`. `unknown_parameter` and `invalid_cursor` name the query parameter in `error.parameter`. | | 401 | `missing_key`, `invalid_key` (unknown or revoked) or `expired_key`. Not counted against any limit. | | 403 | `account_not_active`, `terms_not_accepted` (with `error.agreement_type`), `insufficient_scope` (with `error.scope`), `wrong_account_type` or `ip_not_allowed`. | | 404 | `not_found`: unknown id, a resource of another account (never `403`), or a test helper called with a live key. | | 409 | `duplicate_own_lead` (with `error.lead`), `duplicate_other_referrer` (on create and on a `PATCH` that changes `instagram_handle`), `lead_locked`, `listing_locked`, `invalid_state`, `external_id_taken`, `photos_locked`, `limit_reached` (with `error.limit`) or `idempotency_in_progress`; on the agency endpoints also `offer_taken`, `offer_expired`, `listing_unavailable`, `payment_pending`, `deal_paid`, `undo_window_passed`, `claim_exists` or `warranty_expired`. `invalid_state` carries `error.current_state` — the lead's stage (`draft`, `in_review`, `ready`, `offered`, `accepted`, `in_placement`, `placed`, `withdrawn`, `rejected`, `lost`), `withdrawn` for a fee on a withdrawn listing, `anonymized` for a consent link after her data was erased, or `age_declined` / `age_pending` for a consent grant while her 18+ check is declined or under review — except on agreement accept, where it carries `error.current_version` instead. | | 412 | `precondition_failed`: the `If-Match` value is not the current `ETag`. Read again, then retry. | | 413 | `payload_too_large`: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB. | | 415 | `unsupported_media_type`: send `Content-Type: application/json` (uploads: `multipart/form-data` with a JPEG, PNG or WebP file). | | 422 | `not_ready_for_review` (with `error.blockers`), `idempotency_key_reused` (same key, different body) or `image_unreadable` (an upload that cannot be decoded). | | 429 | `rate_limited`, `concurrency_limited` or `duplicate_limit_reached`. Wait `Retry-After` seconds. Before a key is accepted (per-IP budget for requests without a valid key) the answer has no RateLimit headers. | | 500 | `internal_error`. Safe to retry with the same `Idempotency-Key`; quote `request_id` to support. | | 503 | `not_configured`: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable. | | 502 | `upstream_failed`: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored. | ### Limits Defaults of every API key (test keys get half, rounded up — see Rate limits): - `per-minute`: 100 - `per-day`: 10000 - `duplicate-probes-per-day`: 20 - `concurrent-requests-per-key`: 25 - `max-body-bytes`: 1000000 ### Error codes Every error has the body `ErrorResponse` (`{"error": {type, code, message, …}}`). Branch on `error.code`. | Status | Code | When | Retry | |---|---|---|---| | 400 | `invalid_json` | The body is not valid JSON. | no | | 400 | `invalid_body` | The body is not a JSON object (for example an array). | no | | 400 | `unknown_field` | A request field is not in the contract; `error.field` names it. | no | | 400 | `unknown_parameter` | A query parameter this endpoint does not support; `error.parameter` names it. | no | | 400 | `missing_field` | A required field is missing; `error.details` lists every problem. | no | | 400 | `invalid_field` | A value has the wrong type, length, range or format. | no | | 400 | `missing_contact` | `PATCH /v1/creator/profile` would leave her lead with neither `instagram_handle` nor `other_contact`. | no | | 400 | `age_below_18` | `age` is below 18. | no | | 400 | `consent_required` | `consent_confirmed` is not exactly `true`. | no | | 400 | `invalid_cursor` | `starting_after` or `ending_before` is not one of your leads; `error.parameter` names it. | no | | 401 | `missing_key` | No `Authorization: Bearer` header. | no | | 401 | `invalid_key` | The key is unknown or revoked. | no | | 401 | `expired_key` | The key is past its expiry date. | no | | 401 | `invalid_token` | The creator access token is unknown, revoked, or from the other mode (her grant ended or was revoked: send her through the authorize flow again). | refresh | | 401 | `expired_token` | The creator access token is past its hour: refresh it at `/oauth/token`. | refresh | | 403 | `account_not_active` | The account is pending approval or disabled. With a creator access token: the account that owns the OAuth app (her grant stays and works again once the account is approved). | no | | 403 | `terms_not_accepted` | A write needs the account's terms — and with a live key the API Terms (`api_terms`) and the data protection addendum (`api_dpa`); `error.agreement_type` names one at a time (the API Terms first), so accept and retry until the write goes through. | after accepting | | 403 | `insufficient_scope` | The key lacks the scope in `error.scope`. | no | | 403 | `wrong_account_type` | The endpoint is not for this account type. | no | | 403 | `ip_not_allowed` | The key has an IP allowlist that does not contain the caller. | no | | 403 | `mfa_required` | Portal only: key, webhook and payout changes need a second factor. API keys never get it. | after sign-in | | 403 | `referrer_app_not_allowed` | Creator token of an OAuth app owned by the account that referred her: her consent, 18+ confirmation and creator terms are given only on Creator Guard (consent link or creator portal). Withdrawing consent is never refused. | no | | 404 | `not_found` | Unknown path or id, or a resource of another account. | no | | 405 | `method_not_allowed` | The path exists, the HTTP method does not. | no | | 409 | `duplicate_own_lead` | Your lead with this Instagram handle is past `draft`; `error.lead` names it. | no | | 409 | `duplicate_other_referrer` | Another account already submitted this Instagram handle (create, or a `PATCH` of `instagram_handle`). | no | | 409 | `lead_locked` | Lead fields can no longer change (the lead left `draft`). | no | | 409 | `listing_locked` | The listing is live; its fields and fee can no longer change. | no | | 409 | `photos_locked` | The listing is live; its photos can no longer change (partner and creator endpoints alike). | no | | 409 | `invalid_state` | Not allowed in the current state; `error.current_state` names it (`error.current_version` on agreement accept). | no | | 409 | `offer_taken` | Accepting an offer: another agency accepted her first. | no | | 409 | `offer_expired` | Accepting or declining an offer whose deadline passed. | no | | 409 | `listing_unavailable` | Accepting an offer whose listing was pulled or that we retracted. | no | | 409 | `payment_pending` | The step needs a paid reservation (offer progress, the creator's contact, a warranty claim). | later | | 409 | `deal_paid` | Marking an offer lost after the placement fee was received. A paid deal ends only through a warranty claim or Creator Guard. | no | | 409 | `undo_window_passed` | Undoing an accept after `undo_until`. | no | | 409 | `claim_exists` | A second warranty claim on the same reservation. | no | | 409 | `warranty_expired` | A warranty claim after the warranty ended. | no | | 409 | `external_id_taken` | `external_id` is used by another of your leads. | no | | 409 | `consent_text_outdated` | Granting consent, the 18+ confirmation or accepting the creator terms with a text version that is not the current one; `error.current_version` names it. Show her the current text (`GET /v1/creator/consent-text`) and ask again. A withdrawal never fails for this reason. | after refetch | | 409 | `idempotency_in_progress` | The first request with this `Idempotency-Key` is still running. | yes | | 409 | `limit_reached` | A limit of the account is reached (10 active keys or 10 webhook endpoints per mode, 20 photos per lead, 1,000 open deliveries per endpoint on replay); `error.limit` is the number. | no | | 410 | `version_sunset` | A retired major version (not used in v1 yet). | no | | 412 | `precondition_failed` | `If-Match` is not the current `ETag`. | after refetch | | 413 | `payload_too_large` | The body is larger than 1 MB. | no | | 415 | `unsupported_media_type` | The body is not `application/json`. | no | | 422 | `not_ready_for_review` | Blockers remain; `error.blockers` lists them. | after fixing | | 422 | `idempotency_key_reused` | The same `Idempotency-Key` with a different body. | no | | 422 | `image_unreadable` | The uploaded file is not a readable JPEG, PNG or WebP image. | no | | 429 | `rate_limited` | A rate limit is used up; wait `Retry-After` seconds. | yes | | 429 | `concurrency_limited` | More than 25 requests of this key are in flight. | yes, slower | | 429 | `duplicate_limit_reached` | The daily budget of answers about other accounts' creators is used up. | after Retry-After | | 500 | `internal_error` | Unexpected error on our side; quote `request_id`. | yes | | 502 | `upstream_failed` | A service we depend on failed (text extraction, or the DNS lookup of a webhook URL); nothing was stored. | yes | | 503 | `not_configured` | A setting is missing on our side (for example text extraction), or test mode is briefly unavailable. | no | ### Event types Webhook events and `GET /v1/events`; the payload of each is the `Event` envelope with `data.object`. | Type | When | `data.object` | Sent to | Scope to read it | |---|---|---|---|---| | `lead.created` | A lead was created (API or portal). | `Lead` | The account that owns the lead. | `leads:read` | | `lead.updated` | Lead or listing fields changed; `previous_attributes` names them. | `Lead` | The account that owns the lead. | `leads:read` | | `lead.stage_changed` | The lead moved to another stage; `previous_attributes.stage` is the old one. | `Lead` | The account that owns the lead. | `leads:read` | | `lead.withdrawn` | The lead was withdrawn. | `Lead` | The account that owns the lead. | `leads:read` | | `listing.approved` | Our review approved the listing; it is live for agencies. | `Lead` | The account that owns the lead. | `leads:read` | | `photo.added` | A photo was added (API or portal). | `Photo` | The account that owns the lead. | `leads:read` | | `photo.removed` | A photo was removed; `data.object` is the photo as it was, `url` is `null`. | `Photo` | The account that owns the lead. | `leads:read` | | `consent.granted` | She granted consent on her page. | `Confirmations` | The account that owns the lead. | `leads:read` | | `consent.revoked` | She revoked her consent. | `Confirmations` | The account that owns the lead. | `leads:read` | | `age_confirmation.confirmed` | Her 18+ confirmation was recorded. | `Confirmations` | The account that owns the lead. | `leads:read` | | `commission.created` | A commission was booked for your lead (her placement completed). | `Commission` | The account that owns the lead. | `earnings:read` | | `commission.paid` | We paid a commission; `previous_attributes.status` is the old status. | `Commission` | The account that owns the lead. | `earnings:read` | | `commission.voided` | A commission was voided; `previous_attributes.status` is the old status. | `Commission` | The account that owns the lead. | `earnings:read` | | `agreement.published` | A new version of terms that apply to you was published. | `Agreement` | Every approved account of the type the terms are for; for `api_terms` and `api_dpa` every approved account. | `account:read` | | `api_key.expiring` | A live key expires within 7 days (sent once per key). | `ApiKey` | The account of the key (live keys only). | `keys:manage` | | `webhook_endpoint.disabled` | An endpoint was disabled after 72 hours of failed deliveries. | `WebhookEndpoint` | The account of the endpoint. | `webhooks:manage` | | `offer.created` | We offered a creator to your agency (portal, matching or `POST /v1/test-helpers/offers`). | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.accepted` | The offer was accepted (API or portal); `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.declined` | The offer was declined; `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.expired` | The offer deadline passed before an accept or decline. | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.retracted` | We withdrew the offer (for example the listing was pulled or another agency won her). | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.reopened` | Your retracted offer is open again: the agency that won her undid its accept within the undo window. `previous_attributes.status` is `retracted`. | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.progressed` | Any other status change: contacted, in talks, signed, lost, or back to offered after your own undo; `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.consent_revoked` | She withdrew her consent to share her profile. Sent for every offer your agency holds for her, whatever its status: delete what you keep of her listing and photos. Her listing is hidden (`listing` and `photo_count` `null`, photos refused) while the withdrawal stands, unless your placement of her is completed; an open offer is retracted as well (`offer.retracted`), and an accepted offer whose reservation still awaits payment is retracted with its reservation cancelled (`reservation.cancelled`). | `Offer` | Every agency holding an offer for her. | `offers:read` | | `reservation.created` | An accept created a reservation (`awaiting_payment`). | `Reservation` | The agency the offer was made to. | `reservations:read` | | `reservation.paid` | We received your payment: the reservation is `paid`, her contact is unlocked, the warranty runs. | `Reservation` | The agency the offer was made to. | `reservations:read` | | `reservation.completed` | The warranty ended without a refund. | `Reservation` | The agency the offer was made to. | `reservations:read` | | `reservation.refunded` | We refunded the fee after an accepted warranty claim. | `Reservation` | The agency the offer was made to. | `reservations:read` | | `reservation.cancelled` | The reservation was cancelled: not paid in time, or the accept was undone. | `Reservation` | The agency the offer was made to. | `reservations:read` | | `warranty_claim.created` | A warranty claim was filed on the reservation (API or portal). | `Reservation` | The agency the offer was made to. | `reservations:read` | | `data_export.ready` | A creator's data export that your app requested is ready. Fetch the download link with her token: `GET /v1/creator/data-export/{id}`. | `DataRequestRef` | The account that owns the OAuth app whose creator token requested the export. | `oauth_apps:manage` | | `job.completed` | An asynchronous job your app started finished (`succeeded` or `failed`). `GET /v1/jobs/{id}` with her token has the status and result. | `JobRef` | The account that owns the OAuth app whose creator token started the job. | `oauth_apps:manage` | | `deletion_request.completed` | Creator Guard carried out the deletion request your app sent: her data is anonymised and her login and grants are gone. Stop processing her data in your systems. | `DataRequestRef` | The account that owns the OAuth app whose creator token sent the deletion request (even though her grant no longer exists). | `oauth_apps:manage` | | `ping` | A test send (`POST /v1/webhook-endpoints/{id}/test`). | `{}` | Only the endpoint that was tested. | any key | ### Schemas #### `ApiInfo` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"api"` (exactly) | required | | | `api_version` | string | required | Same as `X-API-Version`. | | `status` | string | required | `beta` today. | | `docs_url` | string (uri) | required | | | `openapi_url` | string (uri) | required | | #### `Account` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"account"` (exactly) | required | | | `id` | string · pattern `^acct_[a-z2-7]{26}$` | required | | | `type` | string | required | `referrer` or `agency`. | | `status` | string | required | `approved` for every key that works (other states answer `403 account_not_active`). | | `display_name` | string or null | required | | | `company_name` | string or null | required | | | `website` | string or null | required | | | `telegram_username` | string or null | required | | | `logo_url` | string or null | required | | | `terms` | array of object | required | One entry per agreement type that applies to the account (`api_terms` and `api_dpa` for every account). | | `limits` | object | required | Limits in effect (defaults or your account's overrides). | #### `Agreement` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"agreement"` (exactly) | required | | | `type` | string | required | `referrer_terms`, `agency_terms`, `warranty_terms`, `api_terms`, `api_dpa` | | `current_version` | integer or null | required | | | `published_at` | string or null (date-time) | required | | | `accepted` | boolean | required | | | `accepted_version` | integer or null | required | | | `accepted_at` | string or null (date-time) | required | | | `acceptances` | array of object | required | Every version the account accepted. | #### `AgreementList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `Agreement` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `AgreementDocument` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"agreement_document"` (exactly) | required | | | `type` | string | required | | | `version` | integer | required | | | `published_at` | string or null (date-time) | required | | | `current` | boolean | required | Whether this is the version to accept. | | `body_md` | string | required | The text as Markdown. | #### `AgreementAccept` | Field | Type | Required | Description | |---|---|---|---| | `version` | integer · ≥ 1 | required | Must be the current published version. | #### `OptionLists` Values in the spelling we store. Lists can change. Full lists: https://docs.creator-guard.com/reference/allowed-values/ | Field | Type | Required | Description | |---|---|---|---| | `object` | `"option_lists"` (exactly) | required | | | `platforms` | array of string | required | | | `languages` | array of string | required | | | `content_types` | array of string | required | | | `niches` | array of string | required | | | `specializations` | array of string | required | | #### `Settings` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"settings"` (exactly) | required | | | `offer_deadline_hours` | integer | required | | | `accept_undo_minutes` | integer | required | | | `payment_due_days` | integer | required | | | `warranty_days` | integer | required | | | `creator_guard_share_percent` | integer | required | Creator Guard's share of a placement fee; yours is the rest. | #### `Money` An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | Field | Type | Required | Description | |---|---|---|---| | `amount_minor` | integer | required | | | `currency` | string | required | `USD`, `EUR` or `GBP` today. | #### `MoneyInput` `{"amount_minor": 150000, "currency": "USD"}` = 1,500.00 USD. `null` clears the fee. | Field | Type | Required | Description | |---|---|---|---| | `amount_minor` | integer · 0–9999999999 | required | | | `currency` | string · one of `USD`, `EUR`, `GBP` | required | | #### `NextActions` What you can do with the lead right now — computed by Creator Guard, so you never re-implement the rules. | Field | Type | Required | Description | |---|---|---|---| | `can_edit_lead` | boolean | required | | | `can_edit_listing` | boolean | required | | | `can_edit_fee` | boolean | required | | | `can_withdraw` | boolean | required | | | `can_submit_for_review` | boolean | required | | | `blockers` | array of string | required | What still keeps her off the marketplace, while the lead is `draft` or `in_review` and the listing is not live (else empty): `age_missing`, `languages_missing`, `country_missing`, `content_types_missing`, `photos_missing` (3 needed), `consent_missing`, `age_confirmation_missing`, `fee_missing`. Every blocker also blocks submit-for-review. `fee_missing` appears only on leads whose fee you set (never on leads our team added for your account). New values may be added. | #### `ListingSummary` The listing summary every lead carries. With `?expand=listing` the lead carries the full Listing object instead (without `photo_count`). | Field | Type | Required | Description | |---|---|---|---| | `status` | string | required | `draft`, `in_review`, `live` or `withdrawn`. | | `placement_fee` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `photo_count` | integer | required | Photos she has. | #### `Photo` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"photo"` (exactly) | required | | | `id` | string · pattern `^photo_[a-z2-7]{26}$` | required | | | `kind` | string | required | | | `is_primary` | boolean | required | | | `consent_status` | string | required | | | `url` | string or null (uri) | required | Signed, valid for 1 hour; `null` when the file could not be signed, for a removed photo and in the replay of an upload. | | `url_expires_at` | string or null (date-time) | required | | | `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required | | | `created_at` | string or null (date-time) | required | | | `version` | integer · ≥ 0 | required | Grows with every change of the photo; events about it carry the same number as `sequence`. | #### `ConsentState` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | required | `pending`, `granted` or `revoked`. | | `granted_at` | string or null (date-time) | required | | | `revoked_at` | string or null (date-time) | required | | #### `AgeConfirmation` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | required | `missing`, `confirmed` or `declined`. | | `confirmed_at` | string or null (date-time) | required | | #### `CreatorLogin` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | required | `none` or `active`. | #### `Confirmations` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"confirmations"` (exactly) | required | | | `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required | | | `consent` | `ConsentState` | required | | | `age_confirmation` | `AgeConfirmation` | required | | | `creator_login` | `CreatorLogin` | required | | #### `Lead` One creator you submitted. New fields may be added within v1; ignore fields you do not know. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"lead"` (exactly) | required | | | `id` | string · pattern `^lead_[a-z2-7]{26}$` | required | | | `external_id` | string or null | required | | | `creator_ref` | string or null · pattern `^CR-[0-9]+$` | required | Her creator number; quote it to support. | | `creator_name` | string | required | | | `instagram_handle` | string or null | required | As stored (normalised username). | | `other_contact` | string or null | required | | | `platforms` | array of string | required | | | `follower_count` | integer or null | required | | | `niche` | string or null | required | | | `notes` | string or null | required | | | `stage` | string | required | `draft`, `in_review`, `ready`, `offered`, `accepted`, `in_placement`, `placed`, `rejected`, `lost` or `withdrawn`. New values may be added. | | `outcome_reason` | string or null | required | Why a lead was rejected or lost. | | `next_actions` | `NextActions` | required | What you can do with the lead right now — computed by Creator Guard, so you never re-implement the rules. | | `listing` | `ListingSummary` or `Listing` | required | The summary; with `?expand=listing` the full Listing object. | | `confirmations` | `Confirmations` | optional | | | `consent` | `LeadConsent` | optional | Her consent and her personal consent link. Links are stored only as hashes, so `url` is shown once: in the `201` that created the lead (a new link, valid at least 30 days). A `200` of `POST /v1/leads` and `GET /v1/leads/{id}` answer `url: null` with the current `expires_at`; `POST /v1/leads/{id}/consent-link` makes a new link. Reading a lead never extends it. | | `photos` | array of `Photo` | optional | Only with `?expand=photos`. | | `created_at` | string (date-time) | required | | | `updated_at` | string (date-time) | required | | | `version` | integer · ≥ 0 | required | Grows with every change of the lead or its listing; events about it carry the same number as `sequence`. `0` until the first change after 1.5.0. | #### `LeadList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `Lead` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | Pass as `starting_after` for the next page; `null` on the last page. | #### `LeadCreate` One creator. Required are only her name and `consent_confirmed`, as in the portal; send every other field you know (a contact and her platforms make her far easier to place). Unknown fields → `400 unknown_field`. Strings are trimmed before they are checked; lengths count after trimming. `null` for an optional field is the same as leaving it out (not for `platforms`: leave it out instead). | Field | Type | Required | Description | |---|---|---|---| | `external_id` | string or null · 1–100 chars | optional | Your own reference, unique within your account. Repeating it returns the existing lead (`200`). | | `creator_name` | string · 1–120 chars | required | Name or alias. | | `instagram_handle` | string or null · 1–200 chars | optional | Username (`@handle`) or profile link (`instagram.com/`). Anything else → `400 invalid_field`. Recognises creators already in the system; without it there is no duplicate check by handle. | | `other_contact` | string or null · 1–200 chars | optional | Any other way to reach her (Telegram, phone, …). | | `platforms` | array of string · at least 1, at most 20, each ≤ 40 chars | optional | Platforms she is on; pick-list values are stored in their spelling. [Allowed values](https://docs.creator-guard.com/reference/allowed-values/). Optional; when sent, at least one entry. | | `follower_count` | integer or null (int32) · 0–2147483647 | optional | Followers on her largest platform. | | `niche` | string or null · 1–80 chars | optional | A pick-list niche is stored in its spelling. [Allowed values](https://docs.creator-guard.com/reference/allowed-values/). | | `notes` | string or null · 1–2000 chars | optional | For our team; never shown to agencies. | | `consent_confirmed` | `true` (exactly) | required | Your declaration that she agreed to be referred and to you sending these details. Must be exactly `true`. | | `listing` | `ListingPatch` | optional | Listing fields. Every field is optional; `null` clears a value, `[]` empties a list. | #### `LeadUpdate` Send only the fields to change; `null` clears an optional field. Lead fields while `can_edit_lead`; `external_id` always. | Field | Type | Required | Description | |---|---|---|---| | `external_id` | string or null · 1–100 chars | optional | | | `creator_name` | string · 1–120 chars | optional | | | `instagram_handle` | string or null · 1–200 chars | optional | | | `other_contact` | string or null · 1–200 chars | optional | | | `platforms` | array of string · at least 1, at most 20, each ≤ 40 chars | optional | | | `follower_count` | integer or null (int32) · 0–2147483647 | optional | | | `niche` | string or null · 1–80 chars | optional | | | `notes` | string or null · 1–2000 chars | optional | | #### `ListingPatch` Listing fields. Every field is optional; `null` clears a value, `[]` empties a list. | Field | Type | Required | Description | |---|---|---|---| | `age` | integer or null · 18–99 | optional | Below 18 → `400 age_below_18`. | | `gender` | string or null · one of `female`, `male`, `trans`, `non_binary`, `other` | optional | | | `origin_country` | string or null · 1–80 chars | optional | | | `languages` | array of string · at most 20, each ≤ 40 chars | optional | | | `english_level` | integer or null · 1–10 | optional | | | `content_types` | array of string · at most 30, each ≤ 40 chars | optional | Content categories she is comfortable with. Values: [allowed values](https://docs.creator-guard.com/reference/allowed-values/). | | `content_freetext` | string or null · 1–2000 chars | optional | | | `has_of_account` | boolean or null | optional | | | `of_verified` | boolean or null | optional | | | `of_current_earnings` | integer or null · 0–2147483647 | optional | USD per month. | | `content_ready` | boolean or null | optional | | | `scripts_ready` | boolean or null | optional | | | `account_access` | string or null · one of `yes`, `no`, `undiscussed` | optional | | | `device` | string or null · 1–200 chars | optional | | | `social_status` | string or null · one of `none`, `ready_to_create`, `existing` | optional | | | `social_preferences` | object | optional | Platform (1–40 characters) → wants to be active there; at most 20 entries. | | `tiktok_ok` | boolean or null | optional | | | `blocked_countries` | array of string · at most 250, each ≤ 80 chars | optional | | | `start_availability` | string or null · one of `now`, `date` | optional | | | `start_date` | string or null (date) | optional | | | `availability_hours_per_week` | number or null · 0–168 | optional | | | `availability_hours_per_day` | number or null · 0–24 | optional | | | `compensation_model` | string or null · one of `revenue_share`, `fixed` | optional | | | `creator_share_percent` | integer or null · 0–100 | optional | | | `fixed_salary` | integer or null · 0–2147483647 | optional | | | `salary_period` | string or null · one of `weekly`, `monthly` | optional | | | `placement_fee` | `MoneyInput` | optional | `{"amount_minor": 150000, "currency": "USD"}` = 1,500.00 USD. `null` clears the fee. | | `notes_public` | string or null · 1–2000 chars | optional | Shown to agencies with the listing. | #### `Listing` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"listing"` (exactly) | required | | | `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required | | | `status` | string | required | `draft`, `in_review`, `live` or `withdrawn`. | | `age` | integer or null | required | | | `gender` | string or null | required | | | `origin_country` | string or null | required | | | `languages` | array of string | required | | | `english_level` | integer or null | required | | | `content_types` | array of string | required | | | `content_freetext` | string or null | required | | | `has_of_account` | boolean or null | required | | | `of_verified` | boolean or null | required | | | `of_current_earnings` | integer or null | required | | | `content_ready` | boolean or null | required | | | `scripts_ready` | boolean or null | required | | | `account_access` | string or null | required | | | `device` | string or null | required | | | `social_status` | string or null | required | | | `social_preferences` | object | required | | | `tiktok_ok` | boolean or null | required | | | `blocked_countries` | array of string | required | | | `start_availability` | string or null | required | | | `start_date` | string or null (date) | required | | | `availability_hours_per_week` | number or null | required | | | `availability_hours_per_day` | number or null | required | | | `compensation_model` | string or null | required | | | `creator_share_percent` | integer or null | required | | | `fixed_salary` | integer or null | required | | | `salary_period` | string or null | required | | | `placement_fee` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `notes_public` | string or null | required | | | `updated_at` | string or null (date-time) | required | | #### `LeadConsent` Her consent and her personal consent link. Links are stored only as hashes, so `url` is shown once: in the `201` that created the lead (a new link, valid at least 30 days). A `200` of `POST /v1/leads` and `GET /v1/leads/{id}` answer `url: null` with the current `expires_at`; `POST /v1/leads/{id}/consent-link` makes a new link. Reading a lead never extends it. | Field | Type | Required | Description | |---|---|---|---| | `status` | string | required | `pending`, `granted` or `revoked`. | | `url` | string or null (uri) | required | Her personal page on app.creator-guard.com — only in the `201` that created the lead; `null` otherwise (stored hashed) and after her data was erased at her request. | | `expires_at` | string or null (date-time) | required | When her current link stops working; a new one: `POST /v1/leads/{id}/consent-link`. `null` after her data was erased. | #### `ConsentLink` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"consent_link"` (exactly) | required | | | `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required | | | `url` | string (uri) | required | Her personal page on app.creator-guard.com — a new link; the previous one can then only be used to withdraw consent. Shown only in this answer. | | `expires_at` | string (date-time) | required | | #### `ClaimLink` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"claim_link"` (exactly) | required | | | `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required | | | `url` | string or null (uri) | required | Her single-use page on app.creator-guard.com (`/claim/`); `null` in an Idempotency-Key replay. | | `expires_at` | string (date-time) | required | | #### `Timeline` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"timeline"` (exactly) | required | | | `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required | | | `events` | array of object | required | Oldest first; only milestones that happened (or, for `warranty_until`, are scheduled). | #### `Earnings` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"earnings"` (exactly) | required | | | `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required | | | `fee` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `creator_guard_amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `your_amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `status` | string or null | required | `expected` (fee set, before completion), `due`, `paid` or `void` (also for a lost, rejected or withdrawn lead without a booked commission); `null` (with every amount `null`) while no fee is set. | #### `AccountPatch` Send only what changes; the same fields and checks as the portal's profile page. Strings are trimmed first. | Field | Type | Required | Description | |---|---|---|---| | `display_name` | string · 1–120 chars | optional | The name agencies and creators see. | | `company_name` | string or null · 0–200 chars | optional | `null` or an empty string clears it. | | `telegram_username` | string | optional | `name`, `@name` or a `t.me/name` link; stored as the name, 5–32 letters, digits or `_`. Cannot be removed. | | `website` | string or null · 0–300 chars | optional | An `https://` (or `http://`) address with a dot in the host; without a scheme `https://` is added. `null` or an empty string clears it. | #### `LogoUpload` | Field | Type | Required | Description | |---|---|---|---| | `file` | string (binary) | required | PNG, JPEG or WebP, at most 2 MB. | #### `ExtractRequest` | Field | Type | Required | Description | |---|---|---|---| | `text` | string · 20–20000 chars | required | Any text about her: profile, chat, notes (at least 20 characters after trimming). Not stored. | #### `ExtractResult` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"extract_result"` (exactly) | required | | | `suggestions` | object | required | Only fields the text supports, each already valid under the rules of `POST /v1/leads`; review them before you send a lead. | #### `PhotoUpload` | Field | Type | Required | Description | |---|---|---|---| | `file` | string (binary) | required | JPEG, PNG or WebP; at most 40 MB and 50 megapixels. Exactly one file part. | | `kind` | string · one of `portrait`, `body`, `content_sample`, `non_nude`, `lingerie`, `professional` | optional | Default `portrait`. | | `is_primary` | string · one of `true`, `false` | optional | `true` makes it her primary photo (default `false`). Her first photo is always primary. | #### `PhotoPatch` | Field | Type | Required | Description | |---|---|---|---| | `kind` | string · one of `portrait`, `body`, `content_sample`, `non_nude`, `lingerie`, `professional` | optional | | | `is_primary` | `true` (exactly) | optional | Makes this her primary photo. Only `true`: make another photo primary instead. | #### `PhotoList` Every photo of the lead (at most 20) on one page: `has_more` is always `false`. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `Photo` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `LeadSummary` The short lead object of `?expand=lead`. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"lead"` (exactly) | required | | | `id` | string · pattern `^lead_[a-z2-7]{26}$` | required | | | `creator_name` | string | required | | | `creator_ref` | string or null · pattern `^CR-[0-9]+$` | required | | | `stage` | string | required | | #### `Commission` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"commission"` (exactly) | required | | | `id` | string · pattern `^com_[a-z2-7]{26}$` | required | | | `lead` | string · pattern `^lead_[a-z2-7]{26}$` or `LeadSummary` | required | The lead id (`lead_…`); with `?expand=lead` a short lead object (stays the id when you can no longer read the lead). | | `creator_ref` | string or null · pattern `^CR-[0-9]+$` | required | | | `status` | string | required | `due` (we owe it), `paid` or `void`. New values may be added. | | `fee_total` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `creator_guard_amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `your_amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `created_at` | string or null (date-time) | required | | | `paid_at` | string or null (date-time) | required | | | `version` | integer · ≥ 0 | required | Grows with every change; events about it carry the same number as `sequence`. | #### `CommissionList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `Commission` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `PayoutDetails` All three are `null` until you save payout details in the portal. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"payout_details"` (exactly) | required | | | `method` | string or null | required | `bank`, `paypal` or `crypto`. | | `destination_masked` | string or null | required | The destination with all but a few characters hidden. | | `updated_at` | string or null (date-time) | required | | #### `ApiKey` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"api_key"` (exactly) | required | | | `id` | string · pattern `^key_[a-z2-7]{26}$` | required | | | `mode` | string | required | `live` or `test`. | | `label` | string or null | required | | | `prefix` | string | required | The start of the key, e.g. `cg_live_ab12`; enough to recognise it. | | `scopes` | array of string | required | | | `ip_allowlist` | array of string | required | CIDR blocks; empty = any address. | | `expires_at` | string or null (date-time) | required | Its expiry, capped by your key policy's maximum age. | | `grace_until` | string or null (date-time) | required | Set on a key that was rolled: it works until then. | | `last_used_at` | string or null (date-time) | required | | | `created_at` | string (date-time) | required | | | `created_via` | string | required | `admin`, `portal` or `api`. | | `revoked_at` | string or null (date-time) | required | | | `rolled_from` | string or null | required | The key (`key_…`) this one replaced in a roll. | | `secret` | string or null | optional | The full key. Only in the answer that made it (create, roll) — `null` in a replay of that answer; never again. | #### `ApiKeyCreate` | Field | Type | Required | Description | |---|---|---|---| | `label` | string or null · 0–100 chars | optional | Trimmed; empty = no label. | | `scopes` | array of `Scope` · at least 1 | required | Only scopes the calling key has (else `403 insufficient_scope`). | | `ip_allowlist` | array of string · at most 20 | optional | CIDR blocks with the host bits zero, e.g. `203.0.113.0/24`; empty = any address. | | `expires_at` | string or null (date-time) | optional | In the future; capped by your key policy's maximum age. | #### `ApiKeyRoll` | Field | Type | Required | Description | |---|---|---|---| | `grace_hours` | integer or null · 0–72 | optional | How long the old key keeps working (default 24; `0` = it stops now). | #### `ApiKeyList` The active keys and those revoked in the last 90 days, on one page. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `ApiKey` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `RequestLog` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"request_log"` (exactly) | required | | | `id` | string · pattern `^req_[a-z2-7]{26}$` | required | The request id (`X-Request-Id`). | | `method` | string | required | | | `route` | string | required | Route template, e.g. `/v1/leads/{id}`. | | `status` | integer | required | | | `error_code` | string or null | required | | | `key` | string or null | required | Key id (`key_…`). | | `duration_ms` | integer | required | | | `created_at` | string (date-time) | required | | #### `RequestLogList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `RequestLog` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `Usage` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"usage"` (exactly) | required | | | `from` | string (date) | required | | | `to` | string (date) | required | | | `granularity` | string | required | `day`. | | `mode` | string | required | `live` or `test` — the mode of the calling key. | | `series` | array of object | required | One entry per UTC day of the range. | | `by_route` | array of object | required | | | `by_key` | array of object | required | | #### `AuditEvent` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"audit_event"` (exactly) | required | | | `id` | string · pattern `^aud_[a-z2-7]{26}$` | required | | | `action` | string | required | e.g. `api_key.created`, `api_key.rolled`, `api_key.revoked`, `webhook_endpoint.created`, `account.updated`, `limits.changed`. New values may be added. | | `actor` | object | required | | | `target` | object or null | required | | | `mode` | string or null | required | `live`, `test`, or `null` for account-wide changes. | | `ip` | string or null | required | | | `user_agent` | string or null | required | | | `details` | object | required | What changed (names and new values; never secrets or creator data). | | `created_at` | string (date-time) | required | | #### `AuditEventList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `AuditEvent` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `EventType` The event types of the catalogue. New types may be added; `ping` is sent only by a test send and cannot be subscribed to. Type: string · one of `lead.created`, `lead.updated`, `lead.stage_changed`, `lead.withdrawn`, `listing.approved`, `photo.added`, `photo.removed`, `consent.granted`, `consent.revoked`, `age_confirmation.confirmed`, `commission.created`, `commission.paid`, `commission.voided`, `agreement.published`, `api_key.expiring`, `webhook_endpoint.disabled`, `offer.created`, `offer.accepted`, `offer.declined`, `offer.expired`, `offer.retracted`, `offer.reopened`, `offer.progressed`, `offer.consent_revoked`, `reservation.created`, `reservation.paid`, `reservation.completed`, `reservation.refunded`, `reservation.cancelled`, `warranty_claim.created`, `data_export.ready`, `job.completed`, `deletion_request.completed`, `ping`. #### `Event` One change. `data.object` is the object as your account may see it when the event is read or delivered; its `object` tells which schema: [Lead](#schema-Lead), [Photo](#schema-Photo), [Confirmations](#schema-Confirmations), [Commission](#schema-Commission), [Agreement](#schema-Agreement), [ApiKey](#schema-ApiKey), [WebhookEndpoint](#schema-WebhookEndpoint), [Offer](#schema-Offer), [Reservation](#schema-Reservation), a reference [DataRequestRef](#schema-DataRequestRef) or [JobRef](#schema-JobRef) (creator-side events: never her data), or `{}` for `ping`. An object that no longer exists is `{"id": …, "object": …, "deleted": true}` (a removed photo: the photo as it was, `url` `null`). New types may be added. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | `live` or `test`. | | `api_version` | string | required | The contract version that rendered the payload. | | `sequence` | integer | required | The `version` the object reached with this change. Drop an event whose `sequence` is not above the last one you applied for that object (`0` for `ping`). | | `data` | object | required | | | `previous_attributes` | object | optional | Only on events about a change: what changed, by contract field name (listing fields under `listing`, `consent` and `age_confirmation` as objects), each with `null` — the old value only for `stage` and `status`. Never creator data. | #### `EventList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `Event` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `WebhookEndpoint` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"webhook_endpoint"` (exactly) | required | | | `id` | string · pattern `^we_[a-z2-7]{26}$` | required | | | `url` | string (uri) | required | | | `description` | string or null | required | | | `event_types` | array of string | required | The subscribed types, or `["*"]` for all. | | `enabled` | boolean | required | | | `disabled_reason` | string or null | required | `manual` (you) or `failing` (72 hours of failed deliveries). | | `created_at` | string (date-time) | required | | | `updated_at` | string (date-time) | required | | | `secret` | string or null | optional | `whsec_…` signing secret. Only in the answers to create and roll — `null` in a replay of that answer; never again. | #### `WebhookEndpointCreate` | Field | Type | Required | Description | |---|---|---|---| | `url` | string · 0–2048 chars · pattern `^https://` | required | https on port 443, no credentials, a host that resolves to public addresses only. | | `event_types` | array of string · at least 1, at most 32 | required | `["*"]` for every type, or event types of [EventType](#schema-EventType) except `ping`. | | `description` | string or null · 0–500 chars | optional | | #### `WebhookEndpointUpdate` Send only what changes. Enabling an endpoint that was disabled as failing restarts its failure clock. | Field | Type | Required | Description | |---|---|---|---| | `url` | string · 0–2048 chars · pattern `^https://` | optional | | | `event_types` | array of string · at least 1, at most 32 | optional | | | `description` | string or null · 0–500 chars | optional | | | `enabled` | boolean | optional | | #### `WebhookEndpointList` Every endpoint of this mode (at most 10) on one page. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `WebhookEndpoint` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `WebhookReplay` | Field | Type | Required | Description | |---|---|---|---| | `from` | string (date-time) | required | At most 30 days ago. | | `to` | string or null (date-time) | optional | After `from`; default now. | #### `ReplayResult` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"webhook_replay"` (exactly) | required | | | `endpoint` | string · pattern `^we_[a-z2-7]{26}$` | required | | | `from` | string (date-time) | required | | | `to` | string (date-time) | required | | | `queued` | integer | required | Deliveries queued (a range that would pass 1,000 open deliveries → `409 limit_reached`, nothing queued). | #### `WebhookDelivery` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"webhook_delivery"` (exactly) | required | | | `id` | string · pattern `^whd_[a-z2-7]{26}$` | required | | | `event` | string | required | Event id (`evt_…`). | | `event_type` | string | required | | | `status` | string | required | `pending`, `sending`, `succeeded` or `failed`. | | `attempt` | integer | required | | | `next_attempt_at` | string or null (date-time) | required | | | `last_status` | integer or null | required | HTTP status your endpoint answered. | | `last_error` | string or null | required | Why the last attempt failed (a short code, e.g. a timeout); `null` after a success. | | `replay` | boolean | required | | | `created_at` | string (date-time) | required | | | `completed_at` | string or null (date-time) | required | | | `attempts` | array of object | required | | #### `WebhookDeliveryList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `WebhookDelivery` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `TestLeadReject` | Field | Type | Required | Description | |---|---|---|---| | `outcome_reason` | string · one of `profile_mismatch`, `not_reachable`, `duplicate`, `quality`, `capacity`, `other` | required | | #### `TestReset` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"sandbox_reset"` (exactly) | required | | | `mode` | `"test"` (exactly) | required | | | `deleted` | object | required | | #### `LeadEvent` An event whose `data.object` is a [Lead](#schema-Lead) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | | `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). | #### `PhotoEvent` An event whose `data.object` is a [Photo](#schema-Photo); for `photo.removed` the photo as it was, with `url` `null`. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | | `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). | #### `ConfirmationsEvent` An event whose `data.object` is a [Confirmations](#schema-Confirmations) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | | `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). | #### `CommissionEvent` An event whose `data.object` is a [Commission](#schema-Commission) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | | `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). | #### `AgreementEvent` An event whose `data.object` is an [Agreement](#schema-Agreement) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | | `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). | #### `ApiKeyEvent` An event whose `data.object` is an [ApiKey](#schema-ApiKey) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | | `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). | #### `WebhookEndpointEvent` An event whose `data.object` is a [WebhookEndpoint](#schema-WebhookEndpoint) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | | `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). | #### `PingEvent` The event of a test send: `data.object` is empty, `sequence` is 0. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | `"ping"` (exactly) | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | #### `UsdInput` An amount in US dollars as integer cents: `{"amount_minor": 300000, "currency": "USD"}` = 3,000.00 USD. Another currency is `400 invalid_field` on `.currency`; `null` clears the value. | Field | Type | Required | Description | |---|---|---|---| | `amount_minor` | integer · ≥ 0 | required | | | `currency` | `"USD"` (exactly) | required | | #### `Flex` Where a creator may be near your criteria instead of matching exactly. A key that is present means "may deviate" (a creator just outside counts as a near match); a missing key means "must match". Levels are the presets of the portal: `age` 3, 8 or 20 (years outside your range), `revenue` `"zero"`, 50 or 100 (percent), `english` 3, 5 or `"any"`, `fee` 25, 50 or 100 (percent above your maximum fee), `split` 10, 20 or 30 (points above your maximum creator share), `stage` `"opposite"`. In the four list keys `also` holds other values that are fine; `[]` means anything else is close too. | Field | Type | Required | Description | |---|---|---|---| | `age` | object | optional | | | `revenue` | object | optional | | | `english` | object | optional | | | `fee` | object | optional | | | `split` | object | optional | | | `stage` | object | optional | | | `niches` | object | optional | | | `platforms` | object | optional | | | `content_types` | object | optional | | | `languages` | object | optional | | #### `FlexInput` The `flex` you send: only the preset levels (anything else is `400 invalid_field` with `field: "flex."`); values in `also` that repeat your primary selection are dropped. `null` = the portal default. | Field | Type | Required | Description | |---|---|---|---| | `age` | object | optional | | | `revenue` | object | optional | | | `english` | object | optional | | | `fee` | object | optional | | | `split` | object | optional | | | `stage` | object | optional | | | `niches` | object | optional | | | `platforms` | object | optional | | | `content_types` | object | optional | | | `languages` | object | optional | | #### `SearchProfile` What we match creators against before we offer them to you. Before your first `PUT` the defaults (`updated_at: null`). | Field | Type | Required | Description | |---|---|---|---| | `object` | `"search_profile"` (exactly) | required | | | `niches` | array of string | required | | | `platforms` | array of string | required | | | `languages` | array of string | required | | | `content_types` | array of string | required | | | `age_min` | integer or null | required | | | `age_max` | integer or null | required | | | `english_level_min` | integer or null | required | | | `revenue_min` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `revenue_max` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `max_placement_fee` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `creator_share_max_percent` | integer or null | required | | | `creator_stage` | string | required | `beginners`, `earning` or `both`. | | `countries_excluded` | array of string | required | | | `capacity_per_month` | integer or null | required | | | `notes` | string or null | required | | | `flex` | `Flex` | required | Where a creator may be near your criteria instead of matching exactly. A key that is present means "may deviate" (a creator just outside counts as a near match); a missing key means "must match". Levels are the presets of the portal: `age` 3, 8 or 20 (years outside your range), `revenue` `"zero"`, 50 or 100 (percent), `english` 3, 5 or `"any"`, `fee` 25, 50 or 100 (percent above your maximum fee), `split` 10, 20 or 30 (points above your maximum creator share), `stage` `"opposite"`. In the four list keys `also` holds other values that are fine; `[]` means anything else is close too. | | `updated_at` | string or null (date-time) | required | | #### `SearchProfilePut` Full replacement: every field is optional, and a field you leave out goes back to its default (`[]`, `null`, `creator_stage: "both"`, the portal `flex`). Pick-list values are stored in the pick-list spelling. Money is US dollars only; `revenue_*` in whole dollars (`amount_minor` a multiple of 100). | Field | Type | Required | Description | |---|---|---|---| | `niches` | array of string · at most 50, each ≤ 100 chars | optional | | | `platforms` | array of string · at most 50, each ≤ 100 chars | optional | | | `languages` | array of string · at most 50, each ≤ 100 chars | optional | | | `content_types` | array of string · at most 50, each ≤ 100 chars | optional | | | `age_min` | integer or null · 18–99 | optional | | | `age_max` | integer or null · 18–99 | optional | Not below `age_min`. | | `english_level_min` | integer or null · 1–10 | optional | | | `revenue_min` | `UsdInput` | optional | An amount in US dollars as integer cents: `{"amount_minor": 300000, "currency": "USD"}` = 3,000.00 USD. Another currency is `400 invalid_field` on `.currency`; `null` clears the value. | | `revenue_max` | `UsdInput` | optional | An amount in US dollars as integer cents: `{"amount_minor": 300000, "currency": "USD"}` = 3,000.00 USD. Another currency is `400 invalid_field` on `.currency`; `null` clears the value. | | `max_placement_fee` | `UsdInput` | optional | An amount in US dollars as integer cents: `{"amount_minor": 300000, "currency": "USD"}` = 3,000.00 USD. Another currency is `400 invalid_field` on `.currency`; `null` clears the value. | | `creator_share_max_percent` | integer or null · 0–100 | optional | | | `creator_stage` | string or null · one of `beginners`, `earning`, `both` | optional | | | `countries_excluded` | array of string · at most 50, each ≤ 100 chars | optional | | | `capacity_per_month` | integer or null · 0–1000 | optional | | | `notes` | string or null · 1–2000 chars | optional | | | `flex` | `FlexInput` | optional | The `flex` you send: only the preset levels (anything else is `400 invalid_field` with `field: "flex."`); values in `also` that repeat your primary selection are dropped. `null` = the portal default. | #### `AgencyProfile` Your agency's public facts. `tier` (`A`, `B`, `C` or `unranked`) and `verified_revenue` are set by Creator Guard. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"agency_profile"` (exactly) | required | | | `country` | string or null | required | | | `website` | string or null | required | | | `team_size` | integer or null | required | | | `years_active` | number or null | required | | | `monthly_revenue` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `managed_creators_count` | integer or null | required | | | `specialization` | array of string | required | | | `references` | string or null | required | | | `tier` | string | required | | | `verified_revenue` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `vetting` | `AgencyVetting` | required | Read-only, set by Creator Guard: where the 5-point vetting of your agency stands. Your agency receives offers with a creator's profile only once `status` is `vetted`; before that a creator who matches your search profile waits (`waiting_matches`) and her offer arrives when the vetting is done. The sandbox (test keys) always reports `vetted` with `waiting_matches: 0`. | | `updated_at` | string or null (date-time) | required | | #### `AgencyVetting` Read-only, set by Creator Guard: where the 5-point vetting of your agency stands. Your agency receives offers with a creator's profile only once `status` is `vetted`; before that a creator who matches your search profile waits (`waiting_matches`) and her offer arrives when the vetting is done. The sandbox (test keys) always reports `vetted` with `waiting_matches: 0`. | Field | Type | Required | Description | |---|---|---|---| | `status` | string | required | One of `registered`, `in_review`, `vetted`. `registered`: account ready, vetting not started; `in_review`: we are vetting your agency; `vetted`: offers reach your account. | | `waiting_matches` | integer · ≥ 0 | required | Creators matched to your agency who wait for your vetting. A count only. | #### `AgencyProfilePatch` Only the fields you send change; `null` clears one (`specialization`: send `[]`). `tier`, `verified_revenue` and `vetting` cannot be sent (`400 unknown_field`). | Field | Type | Required | Description | |---|---|---|---| | `country` | string or null · 1–100 chars | optional | | | `website` | string or null · 0–300 chars | optional | An `https://` URL. | | `team_size` | integer or null · 0–100000 | optional | | | `years_active` | number or null · 0–99.9 | optional | At most one decimal, e.g. `3.5`. | | `monthly_revenue` | `UsdInput` | optional | An amount in US dollars as integer cents: `{"amount_minor": 300000, "currency": "USD"}` = 3,000.00 USD. Another currency is `400 invalid_field` on `.currency`; `null` clears the value. | | `managed_creators_count` | integer or null · 0–100000 | optional | | | `specialization` | array of string · at most 20, each ≤ 100 chars | optional | | | `references` | string or null · 1–2000 chars | optional | | #### `OfferListing` The creator's listing as agencies see it — the fields of [Listing](#schema-Listing) without its lead, status and the referrer's data. `placement_fee` is the price of this offer. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"listing"` (exactly) | required | | | `age` | integer or null | required | | | `gender` | string or null | required | | | `origin_country` | string or null | required | | | `languages` | array of string | required | | | `english_level` | integer or null | required | | | `content_types` | array of string | required | | | `content_freetext` | string or null | required | | | `has_of_account` | boolean or null | required | | | `of_verified` | boolean or null | required | | | `of_current_earnings` | integer or null | required | | | `content_ready` | boolean or null | required | | | `scripts_ready` | boolean or null | required | | | `account_access` | string or null | required | | | `device` | string or null | required | | | `social_status` | string or null | required | | | `social_preferences` | object | required | | | `tiktok_ok` | boolean or null | required | | | `blocked_countries` | array of string | required | | | `start_availability` | string or null | required | | | `start_date` | string or null (date) | required | | | `availability_hours_per_week` | number or null | required | | | `availability_hours_per_day` | number or null | required | | | `compensation_model` | string or null | required | | | `creator_share_percent` | integer or null | required | | | `fixed_salary` | integer or null | required | | | `salary_period` | string or null | required | | | `placement_fee` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `notes_public` | string or null | required | | | `updated_at` | string or null (date-time) | required | | #### `OfferNextActions` What you can do with the offer now — so you never re-implement the rules. | Field | Type | Required | Description | |---|---|---|---| | `can_accept` | boolean | required | | | `can_decline` | boolean | required | | | `can_undo_accept` | boolean | required | | | `can_mark_contacted` | boolean | required | | | `can_mark_in_talks` | boolean | required | | | `can_mark_signed` | boolean | required | | | `can_mark_lost` | boolean | required | | #### `ReservationSummary` The reservation your accept created; the whole object: `GET /v1/reservations/{id}`. | Field | Type | Required | Description | |---|---|---|---| | `id` | string · pattern `^res_[a-z2-7]{26}$` | required | | | `status` | string | required | `awaiting_payment`, `paid`, `completed`, `refunded` or `cancelled`. | | `amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `payment_reference` | string or null | required | | | `payment_due_at` | string or null (date-time) | required | | | `paid_at` | string or null (date-time) | required | | | `warranty_until` | string or null (date-time) | required | | #### `Offer` A creator we offered to your agency. Never her contact details, the referrer or internal notes — the contact comes with `GET /v1/reservations/{id}/creator` after payment. Her name too only after payment; until then she is her creator number (`creator_ref`). New fields may be added within v1. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"offer"` (exactly) | required | | | `id` | string · pattern `^offer_[a-z2-7]{26}$` | required | | | `status` | string | required | `offered`, `accepted`, `declined`, `expired`, `retracted`, `contacted`, `in_talks`, `signed` or `lost`. An open offer whose deadline passed reads `expired` at once. | | `creator_name` | string or null | required | `null` until your agency paid for her (a reservation of yours for her that is `paid` or `completed`; a refunded one does not count). Use `creator_ref` before that. | | `creator_ref` | string or null | required | Her creator number, e.g. `CR-1047`. | | `expires_at` | string or null (date-time) | required | The deadline to accept or decline. | | `accepted_at` | string or null (date-time) | required | | | `undo_until` | string or null (date-time) | required | Until when `undo-accept` works (while unpaid). | | `agency_note` | string or null | required | | | `outcome_reason` | string or null | required | Set on `lost`: `profile_mismatch`, `not_reachable`, `duplicate`, `quality`, `capacity` or `other`. | | `listing` | `OfferListing` or null | required | `null` once the offer is declined, expired, retracted or lost without a paid reservation, and while she has withdrawn her consent (event `offer.consent_revoked`) — unless your placement of her is completed. | | `photo_count` | integer or null | required | Photos she agreed to share; `null` while the listing is hidden. | | `reservation` | `ReservationSummary` or null | required | | | `next_actions` | `OfferNextActions` | required | What you can do with the offer now — so you never re-implement the rules. | | `match` | `OfferMatch` or null | required | How well she fits your search profile (`GET /v1/search-profile`), checked with the same rules as our own matching. `null` while you have no search profile (or nothing filled in) and while her listing is hidden. Criterion names and results only: `niche` and `platforms` are only ever `hit` or `miss` (a close match within your tolerance shows as `hit`, while `score` still counts it ½). | | `created_at` | string (date-time) | required | | | `updated_at` | string (date-time) | required | | #### `OfferList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `Offer` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `OfferMatch` The match of an offer against your search profile. Criteria you left empty are not checked. | Field | Type | Required | Description | |---|---|---|---| | `score` | number · ≥ 0 | required | Criteria met; a close match (within the tolerance you allowed, or a value she has not filled in yet) counts ½. Sort by score / total, knocked-out offers last. | | `total` | integer · ≥ 1 | required | Criteria checked. | | `knocked_out` | boolean | required | `true` when a must-match criterion (one without tolerance; the country always) is a miss. | | `criteria` | array of `OfferMatchCriterion` | required | | #### `OfferMatchCriterion` | Field | Type | Required | Description | |---|---|---|---| | `key` | string | required | `content_types`, `niche`, `languages`, `platforms`, `age`, `english`, `revenue`, `fee`, `split`, `stage` or `country`. New keys may be added within v1. | | `result` | string | required | `hit`, `near` (counts ½) or `miss`; `niche` and `platforms` are only `hit` or `miss`. New values may be added within v1. | | `must` | boolean | required | Must match: a miss knocks her out. | #### `OfferPhoto` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"photo"` (exactly) | required | | | `id` | string · pattern `^photo_[a-z2-7]{26}$` | required | | | `kind` | string | required | | | `is_primary` | boolean | required | | | `url` | string or null | required | Signed link, valid for one hour. | | `url_expires_at` | string or null (date-time) | required | | #### `OfferPhotoList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `OfferPhoto` | required | | | `has_more` | boolean | required | Always `false`: every photo on one page. | | `next_cursor` | string or null | required | | #### `OfferPatch` | Field | Type | Required | Description | |---|---|---|---| | `agency_note` | string or null · 1–500 chars | required | Your note (trimmed); `null` clears it. | #### `OfferDecline` | Field | Type | Required | Description | |---|---|---|---| | `note` | string · 50–500 chars | required | Why she is not a fit, 50–500 characters after trimming. | #### `OfferMarkLost` | Field | Type | Required | Description | |---|---|---|---| | `outcome_reason` | string · one of `profile_mismatch`, `not_reachable`, `duplicate`, `quality`, `capacity`, `other` | required | | #### `WarrantyClaim` | Field | Type | Required | Description | |---|---|---|---| | `reason` | string | required | | | `note` | string or null | required | | | `filed_at` | string or null (date-time) | required | | #### `ReservationNextActions` | Field | Type | Required | Description | |---|---|---|---| | `can_file_warranty_claim` | boolean | required | | | `can_view_creator` | boolean | required | | #### `Reservation` What your accept reserved: the fee to transfer, its payment reference and due date, then payment, warranty and your warranty claim. New fields may be added within v1. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"reservation"` (exactly) | required | | | `id` | string · pattern `^res_[a-z2-7]{26}$` | required | | | `offer` | string or null | required | The offer (`offer_…`). | | `status` | string | required | `awaiting_payment`, `paid` (her contact is unlocked, the warranty runs), `completed`, `refunded` or `cancelled`. | | `creator_name` | string or null | required | `null` until your agency paid for her (`paid` or `completed`; also `null` again after a refund). | | `creator_ref` | string or null | required | | | `amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. | | `payment_reference` | string | required | Put it on your bank transfer. | | `payment_due_at` | string or null (date-time) | required | | | `paid_at` | string or null (date-time) | required | | | `warranty_until` | string or null (date-time) | required | | | `completed_at` | string or null (date-time) | required | | | `refunded_at` | string or null (date-time) | required | | | `warranty_claim` | `WarrantyClaim` or null | required | | | `next_actions` | `ReservationNextActions` | required | | | `created_at` | string or null (date-time) | required | | | `updated_at` | string or null (date-time) | required | | #### `ReservationList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `Reservation` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `ReservationCreator` Her contact, after payment only. Never the referrer, internal notes or her consent records. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"reservation_creator"` (exactly) | required | | | `reservation` | string · pattern `^res_[a-z2-7]{26}$` | required | | | `creator_name` | string | required | | | `creator_ref` | string or null | required | | | `instagram_handle` | string or null | required | | | `other_contact` | string or null | required | | | `platforms` | array of string | required | | | `follower_count` | integer or null | required | | | `niche` | string or null | required | | #### `WarrantyClaimCreate` | Field | Type | Required | Description | |---|---|---|---| | `reason` | string · one of `creator_unreachable`, `no_show`, `false_data`, `contract_refused`, `other` | required | | | `note` | string or null · 0–2000 chars | optional | Trimmed; blank counts as no note. | #### `TestOfferCreate` Every field is optional. | Field | Type | Required | Description | |---|---|---|---| | `creator_name` | string · 1–120 chars | optional | Default: a generated test name. The offer shows it only after `…/mark-paid`, like a live offer. | | `placement_fee` | `MoneyInput` | optional | `{"amount_minor": 150000, "currency": "USD"}` = 1,500.00 USD. `null` clears the fee. | | `expires_in_hours` | integer · 1–720 | optional | Default: the offer deadline of `GET /v1/settings`. | #### `TestReservationRefund` | Field | Type | Required | Description | |---|---|---|---| | `reason` | string · one of `creator_unreachable`, `no_show`, `false_data`, `contract_refused`, `other` | optional | Default: the reason of your warranty claim, else `other`. | #### `ClockAdvance` | Field | Type | Required | Description | |---|---|---|---| | `hours` | integer · 1–720 | required | | #### `ClockAdvanceResult` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"clock_advance"` (exactly) | required | | | `hours` | integer | required | | | `expired_offers` | integer | required | | | `cancelled_reservations` | integer | required | | | `completed_reservations` | integer | required | | #### `OfferEvent` An event whose `data.object` is an [Offer](#schema-Offer) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | | `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). | #### `ReservationEvent` An event whose `data.object` is a [Reservation](#schema-Reservation) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | | `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). | #### `CreatorScope` What a creator lets an OAuth app do for her (request values; new scopes may be added). An app asks for a subset of its registered scopes. Type: string · one of `creator.profile:read`, `creator.profile:write`, `creator.photos:write`, `creator.consent:write`, `creator.support`, `creator.privacy`. #### `OAuthApp` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"oauth_app"` (exactly) | required | | | `id` | string · pattern `^app_[a-z2-7]{26}$` | required | | | `mode` | string | required | `live` or `test` (the mode of the key that registered it). | | `client_id` | string · pattern `^cgcl_(live\|test)_[0-9a-f]{32}$` | required | Public; sent to `/oauth/authorize` and `/oauth/token`. | | `name` | string | required | Shown to the creator on the consent screen. | | `logo_url` | string or null (uri) | required | | | `privacy_url` | string (uri) | required | | | `redirect_uris` | array of string | required | Matched exactly, character for character. Empty only while the app is disabled. | | `scopes` | array of string | required | Creator scopes ([CreatorScope](#schema-CreatorScope)). | | `confidential` | boolean | required | `true`: a server-side app with a client secret; `false`: a public client (PKCE only). | | `secret_prefix` | string or null | required | The start of the current client secret, e.g. `cgcs_live_Ab3x`; `null` for a public client. | | `enabled` | boolean | required | `false` while the app is disabled: unknown to `/oauth/authorize`, and `/oauth/token` answers `unauthorized_client` (existing grants are kept). Send `redirect_uris` in `PATCH /v1/oauth-apps/{id}` to enable it again. | | `disabled_reason` | string or null | required | `member_offboarded`: removing a member (or lowering her role below admin) removed every redirect URI that one of her keys had added, and none was left. `null` while enabled. | | `created_at` | string (date-time) | required | | | `updated_at` | string (date-time) | required | | | `client_secret` | string or null | optional | `cgcs_live_…` / `cgcs_test_…`. Only in the answers to create and roll (`null` for a public client, and in a replay of that answer); never again. | #### `OAuthAppCreate` | Field | Type | Required | Description | |---|---|---|---| | `name` | string · 3–60 chars | required | Trimmed. | | `redirect_uris` | array of string · at least 1, at most 10, each ≤ 2000 chars | required | Distinct; https, no fragment, no user info, no wildcard, no private or loopback host. Test keys may also use `http://localhost:` or `http://127.0.0.1:`. | | `logo_url` | string or null · 0–2000 chars · pattern `^https://` | optional | | | `privacy_url` | string · 0–2000 chars · pattern `^https://` | required | Your privacy policy, linked on the consent screen. | | `scopes` | array of `CreatorScope` · at least 1 | required | Distinct. | | `confidential` | boolean | required | | #### `OAuthAppUpdate` Send only what changes. `logo_url: null` removes the logo. | Field | Type | Required | Description | |---|---|---|---| | `name` | string · 3–60 chars | optional | | | `redirect_uris` | array of string · at least 1, at most 10, each ≤ 2000 chars | optional | | | `logo_url` | string or null · 0–2000 chars · pattern `^https://` | optional | | | `privacy_url` | string · 0–2000 chars · pattern `^https://` | optional | | | `scopes` | array of `CreatorScope` · at least 1 | optional | | | `confidential` | boolean | optional | Only its current value; it cannot change. | #### `OAuthAppList` Every OAuth app of this mode (at most 10) on one page. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `OAuthApp` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `OAuthTestCodeCreate` | Field | Type | Required | Description | |---|---|---|---| | `client_id` | string · pattern `^cgcl_test_[0-9a-f]{32}$` | required | A test-mode app of your account. | | `lead_id` | string · pattern `^lead_[a-z2-7]{26}$` | required | A sandbox lead you may connect (you submitted it, or you hold a paid reservation for it). | | `redirect_uri` | string · 0–2000 chars | required | One of the app's registered redirect URIs, character for character. | | `scopes` | array of `CreatorScope` · at least 1 | required | A subset of the app's scopes; repeats are ignored. | | `code_challenge` | string · pattern `^[A-Za-z0-9_-]{43}$` | required | BASE64URL(SHA256(code_verifier)) without padding (PKCE S256). | #### `OAuthTestCode` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"oauth_test_code"` (exactly) | required | | | `code` | string · pattern `^cgac_[A-Za-z0-9]{43}$` | required | The authorization code; exchange it at `/oauth/token` with `grant_type=authorization_code`. | | `expires_in` | `60` (exactly) | required | Seconds. | #### `Creator` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"creator"` (exactly) | required | | | `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required | Her lead. | | `creator_name` | string | required | | | `stage` | string | required | Same stages as `lead.stage`. | | `next_actions` | object | required | | | `placement` | object or null | required | The agency she was placed with, once it paid; `null` before. | | `updated_at` | string or null (date-time) | required | | #### `CreatorProfile` Her contact fields and the listing fields she edits herself. Never fees, deal terms or `of_verified`. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"creator_profile"` (exactly) | required | | | `lead` | object | required | | | `listing` | object | required | | | `can_edit_lead` | boolean | required | Contact fields can change while the lead is `submitted` (else `409 lead_locked`). | | `can_edit_listing` | boolean | required | Listing fields can change until the listing is live (else `409 listing_locked`). | | `updated_at` | string or null (date-time) | required | | #### `CreatorProfilePatch` Send only what changes; `null` clears a value. Any other field (fees, deal terms, `of_verified`, partner fields) is `400 unknown_field`. | Field | Type | Required | Description | |---|---|---|---| | `lead` | object | optional | | | `listing` | object | optional | | #### `CreatorPhoto` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"photo"` (exactly) | required | | | `id` | string · pattern `^photo_[a-z2-7]{26}$` | required | | | `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required | | | `kind` | string | required | | | `is_primary` | boolean | required | | | `consent_status` | string | required | | | `url` | string or null (uri) | required | Signed, valid for 1 hour; `null` when it could not be signed and in the replay of an upload. | | `url_expires_at` | string or null (date-time) | required | | | `created_at` | string or null (date-time) | required | | #### `CreatorPhotoList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `CreatorPhoto` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `CreatorConsentEvent` One entry of her consent ledger. Never carries her IP address or browser. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"consent_event"` (exactly) | required | | | `id` | string · pattern `^cev_[a-z2-7]{26}$` | required | | | `kind` | string | required | `consent_granted`, `consent_revoked`, `age_confirmed` or `creator_terms_accepted`. | | `text_kind` | string | required | | | `text_version` | integer | required | | | `channel` | string or null | required | Where she decided: `hosted_link`, `hosted_portal`, `admin`, `legacy` or `oauth_app:app_…` (the app that sent it). | | `created_at` | string (date-time) | required | | #### `CreatorConsentState` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"consent_state"` (exactly) | required | | | `consent` | object | required | | | `age_confirmation` | object | required | | | `events` | array of `CreatorConsentEvent` | required | Oldest first. | #### `ConsentText` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"consent_text"` (exactly) | required | | | `kind` | string | required | | | `version` | integer | required | Send it as `text_version` (creator terms: `version`) with her decision. | | `locale` | string | required | | | `body_md` | string | required | Markdown. Show it to her in full before she decides. | | `sha256` | string | required | | | `published_at` | string or null (date-time) | required | | #### `ConsentDecision` The text version she was shown. Required for a grant and the 18+ confirmation (`409 consent_text_outdated` with `current_version` when it is not the current one); optional for a withdrawal, which is never refused because of the text. | Field | Type | Required | Description | |---|---|---|---| | `text_version` | integer · ≥ 1 | optional | | | `locale` | string · pattern `^[a-z]{2}$` | optional | The language of the text she saw, default `en`. | #### `CreatorAgreement` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"creator_agreement"` (exactly) | required | | | `type` | string | required | | | `current_version` | integer or null | required | | | `accepted_version` | integer or null | required | | | `accepted_at` | string or null (date-time) | required | | #### `CreatorAgreementList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `CreatorAgreement` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `CreatorTermsAccept` | Field | Type | Required | Description | |---|---|---|---| | `version` | integer · ≥ 1 | required | The current version (`409 consent_text_outdated` otherwise). | #### `SupportTicket` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"support_ticket"` (exactly) | required | | | `id` | string · pattern `^tkt_[a-z2-7]{26}$` | required | | | `subject` | string | required | | | `status` | string | required | | | `created_at` | string (date-time) | required | | | `updated_at` | string (date-time) | required | | | `last_message_at` | string or null (date-time) | required | | #### `SupportTicketList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `SupportTicket` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `SupportTicketCreate` | Field | Type | Required | Description | |---|---|---|---| | `subject` | string · 3–200 chars | required | Trimmed. | | `body` | string · 1–5000 chars | required | Her first message; trimmed. | #### `SupportMessage` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"support_message"` (exactly) | required | | | `id` | string · pattern `^msg_[a-z2-7]{26}$` | required | | | `ticket` | string · pattern `^tkt_[a-z2-7]{26}$` | required | | | `body` | string | required | | | `from_staff` | boolean | required | | | `created_at` | string (date-time) | required | | #### `SupportMessageList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `SupportMessage` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `SupportReply` | Field | Type | Required | Description | |---|---|---|---| | `body` | string · 1–5000 chars | required | Trimmed. | #### `Job` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"job"` (exactly) | required | | | `id` | string · pattern `^job_[a-z2-7]{26}$` | required | | | `type` | string | required | `data_export`. | | `status` | string | required | `queued`, `running`, `succeeded` or `failed`. | | `progress` | integer or null · 0–100 | required | | | `result` | object or null | required | After success: the data request that holds the download. | | `error_code` | string or null | required | Why it failed, e.g. `timeout`, `upload_failed`, `lead_anonymized`. Request a new export. | | `created_at` | string (date-time) | required | | | `finished_at` | string or null (date-time) | required | | #### `DataRequest` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"data_request"` (exactly) | required | | | `id` | string · pattern `^dreq_[a-z2-7]{26}$` | required | | | `kind` | string | required | `export` or `deletion`. | | `status` | string | required | `open`, `ready` (export to download), `completed`, `rejected`, `failed` or `expired`. | | `job` | string or null | required | The export job (`job_…`); `null` for a deletion request. | | `expires_at` | string or null (date-time) | required | Until when the export can be downloaded (7 days after it was ready). | | `created_at` | string (date-time) | required | | | `completed_at` | string or null (date-time) | required | | | `download_url` | string or null (uri) | optional | Only on `GET /v1/creator/data-export/{id}`: a JSON file, signed until `download_url_expires_at` (1 hour at most, never past `expires_at`; each call signs a new link); `null` unless `status` is `ready`. | | `download_url_expires_at` | string or null (date-time) | optional | | #### `ConnectedApp` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"connected_app"` (exactly) | required | | | `id` | string · pattern `^app_[a-z2-7]{26}$` | required | | | `name` | string | required | | | `logo_url` | string or null (uri) | required | | | `privacy_url` | string (uri) | required | | | `owner_name` | string | required | The partner or agency behind the app. | | `scopes` | array of string | required | | | `connected_at` | string or null (date-time) | required | | | `last_used_at` | string or null (date-time) | required | | #### `ConnectedAppList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `ConnectedApp` | required | | | `has_more` | boolean | required | | | `next_cursor` | string or null | required | | #### `DataRequestRef` A reference to a creator's data request (export or deletion) — never her data, IP or browser. Read it with her access token: `GET /v1/creator/data-export/{id}` for an export. `deleted: true` when it is no longer visible to your account. | Field | Type | Required | Description | |---|---|---|---| | `id` | string · pattern `^dreq_[a-z2-7]{26}$` | required | | | `object` | `"data_request"` (exactly) | required | | | `deleted` | `true` (exactly) | optional | Only when the request no longer exists for your account. | #### `JobRef` A reference to an asynchronous job. Read its status and result with the creator's access token: `GET /v1/jobs/{id}`. `deleted: true` when it is no longer visible to your account. | Field | Type | Required | Description | |---|---|---|---| | `id` | string · pattern `^job_[a-z2-7]{26}$` | required | | | `object` | `"job"` (exactly) | required | | | `deleted` | `true` (exactly) | optional | Only when the job no longer exists for your account. | #### `DataRequestEvent` An event whose `data.object` is a [DataRequestRef](#schema-DataRequestRef): `{"id": "dreq_…", "object": "data_request"}`. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | #### `JobEvent` An event whose `data.object` is a [JobRef](#schema-JobRef): `{"id": "job_…", "object": "job"}`. | Field | Type | Required | Description | |---|---|---|---| | `object` | `"event"` (exactly) | required | | | `id` | string · pattern `^evt_[a-z2-7]{26}$` | required | | | `type` | string | required | | | `created_at` | string (date-time) | required | | | `mode` | string | required | | | `api_version` | string | required | | | `sequence` | integer | required | | | `data` | object | required | | #### `Member` A person who can sign in to the account (`status` `active`) or an open invitation (`invited`). | Field | Type | Required | Description | |---|---|---|---| | `object` | `"member"` (exactly) | required | | | `id` | string | required | `mem_…` for a person, `inv_…` for an invitation. Use it with `DELETE /v1/members/{id}`. | | `email` | string | required | Lower-case email address of the login or the invitation. | | `role` | string | required | `owner`, `admin`, `developer` or `viewer` — https://docs.creator-guard.com/members/ | | `status` | string | required | `active` or `invited`. New values may be added. | | `email_verified` | boolean or null | required | People: `false` when the login was created on the join page — whoever opened the link set its password, nobody proved the address; `true` otherwise. `null` for invitations. | | `created_at` | string (date-time) | required | When the person joined or the invitation was created. | | `expires_at` | string or null (date-time) | required | Invitations: when the link stops working (48 hours). `null` for people. | | `join_url` | string or null (uri) | required | Only in the first answer to `POST /v1/members`: the one-time link for the person. `null` everywhere else, also in an `Idempotency-Key` replay. | #### `MemberInvite` | Field | Type | Required | Description | |---|---|---|---| | `email` | string · 3–254 chars | required | The address the person signs in with; compared without case and surrounding whitespace. | | `role` | string · one of `developer`, `viewer` | required | Admins are invited in the portal only (by an owner or admin with two-factor authentication). The owner is the login the account was created with and is never invited. | #### `MemberList` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"list"` (exactly) | required | | | `data` | array of `Member` | required | | | `has_more` | boolean | required | Always `false`: the list is not paginated. | | `next_cursor` | string or null | required | | #### `MemberDeleted` | Field | Type | Required | Description | |---|---|---|---| | `object` | `"member"` (exactly) | required | | | `id` | string | required | | | `deleted` | `true` (exactly) | required | | #### `ErrorResponse` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | required | | `error` object: | Field | Type | Required | Description | |---|---|---|---| | `type` | string | required | `invalid_request`, `authentication`, `permission`, `rate_limit` or `api_error`. | | `code` | `ErrorCode` | required | Stable, machine-readable error code. Branch on this, not on `message`. New codes may be added within v1. | | `message` | string | required | For a developer reading a log; may change. Never branch on it. | | `doc_url` | string (uri) | required | https://docs.creator-guard.com/errors/# | | `request_id` | string | required | Same as `X-Request-Id`. | | `field` | string | optional | The request field the error is about (first one when there are several). | | `details` | array of object | optional | Every field problem of the request, not just the first. | | `lead` | object or null | optional | With `duplicate_own_lead`: your existing lead. | | `parameter` | string | optional | With `unknown_parameter` and `invalid_cursor`: the query parameter. | | `agreement_type` | string | optional | With `terms_not_accepted`. | | `scope` | string | optional | With `insufficient_scope`: the scope the key lacks. | | `blockers` | array of string | optional | With `not_ready_for_review`. | | `current_state` | string | optional | With `invalid_state`: the state that blocks the call. | | `current_version` | integer | optional | With `invalid_state` on agreement accept: the version to accept. | | `limit` | integer | optional | With `limit_reached`: the limit that is reached. | #### `Scope` Scopes a key can carry. Each operation names the one it needs. Scopes of later endpoints are added with them. `account:read`, `account:write`, `agreements:write`, `keys:manage`, `webhooks:manage`, `leads:read`, `leads:write`, `photos:write`, `earnings:read`, `offers:read`, `offers:write`, `reservations:read`, `reservations:write`, `search_profile:write`, `extract`, `usage:read`, `audit:read`, `oauth_apps:manage`, `members:manage` --- # Events Source: https://docs.creator-guard.com/events/ An event records one change. The same events go to your [webhooks](https://docs.creator-guard.com/webhooks/) and into `GET /v1/events`, which keeps the last **30 days**. ## The event object | Field | Meaning | |---|---| | `id` | `evt_…`; the same for every retry and replay | | `type` | One of the types below | | `created_at` | When the change happened | | `mode` | `live` or `test` | | `api_version` | The contract version that rendered `data` | | `sequence` | The `version` the object reached with this change — drop events whose `sequence` is not above the last one you applied for that object (`0` for `ping`) | | `data.object` | The object as your account may see it when the event is read or delivered; an object that no longer exists is `{"id": …, "object": …, "deleted": true}` — except a removed photo, which `photo.removed` carries as it was when it was removed (stored with the event, without file or storage path) | | `previous_attributes` | Only on events about a change: the changed fields by name, each `null` — except `stage` and `status`, which carry the old value. Never creator data. | Unknown event types may be added within v1: ignore types you do not handle. ## Catalogue | Type | When | `data.object` | Sent to | Scope to read it | |---|---|---|---|---| | `lead.created` | A lead was created (API or portal). | `Lead` | The account that owns the lead. | `leads:read` | | `lead.updated` | Lead or listing fields changed; `previous_attributes` names them. | `Lead` | The account that owns the lead. | `leads:read` | | `lead.stage_changed` | The lead moved to another stage; `previous_attributes.stage` is the old one. | `Lead` | The account that owns the lead. | `leads:read` | | `lead.withdrawn` | The lead was withdrawn. | `Lead` | The account that owns the lead. | `leads:read` | | `listing.approved` | Our review approved the listing; it is live for agencies. | `Lead` | The account that owns the lead. | `leads:read` | | `photo.added` | A photo was added (API or portal). | `Photo` | The account that owns the lead. | `leads:read` | | `photo.removed` | A photo was removed; `data.object` is the photo as it was, `url` is `null`. | `Photo` | The account that owns the lead. | `leads:read` | | `consent.granted` | She granted consent on her page. | `Confirmations` | The account that owns the lead. | `leads:read` | | `consent.revoked` | She revoked her consent. | `Confirmations` | The account that owns the lead. | `leads:read` | | `age_confirmation.confirmed` | Her 18+ confirmation was recorded. | `Confirmations` | The account that owns the lead. | `leads:read` | | `commission.created` | A commission was booked for your lead (her placement completed). | `Commission` | The account that owns the lead. | `earnings:read` | | `commission.paid` | We paid a commission; `previous_attributes.status` is the old status. | `Commission` | The account that owns the lead. | `earnings:read` | | `commission.voided` | A commission was voided; `previous_attributes.status` is the old status. | `Commission` | The account that owns the lead. | `earnings:read` | | `agreement.published` | A new version of terms that apply to you was published. | `Agreement` | Every approved account of the type the terms are for; for `api_terms` and `api_dpa` every approved account. | `account:read` | | `api_key.expiring` | A live key expires within 7 days (sent once per key). | `ApiKey` | The account of the key (live keys only). | `keys:manage` | | `webhook_endpoint.disabled` | An endpoint was disabled after 72 hours of failed deliveries. | `WebhookEndpoint` | The account of the endpoint. | `webhooks:manage` | | `offer.created` | We offered a creator to your agency (portal, matching or `POST /v1/test-helpers/offers`). | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.accepted` | The offer was accepted (API or portal); `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.declined` | The offer was declined; `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.expired` | The offer deadline passed before an accept or decline. | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.retracted` | We withdrew the offer (for example the listing was pulled or another agency won her). | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.reopened` | Your retracted offer is open again: the agency that won her undid its accept within the undo window. `previous_attributes.status` is `retracted`. | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.progressed` | Any other status change: contacted, in talks, signed, lost, or back to offered after your own undo; `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` | | `offer.consent_revoked` | She withdrew her consent to share her profile. Sent for every offer your agency holds for her, whatever its status: delete what you keep of her listing and photos. Her listing is hidden (`listing` and `photo_count` `null`, photos refused) while the withdrawal stands, unless your placement of her is completed; an open offer is retracted as well (`offer.retracted`), and an accepted offer whose reservation still awaits payment is retracted with its reservation cancelled (`reservation.cancelled`). | `Offer` | Every agency holding an offer for her. | `offers:read` | | `reservation.created` | An accept created a reservation (`awaiting_payment`). | `Reservation` | The agency the offer was made to. | `reservations:read` | | `reservation.paid` | We received your payment: the reservation is `paid`, her contact is unlocked, the warranty runs. | `Reservation` | The agency the offer was made to. | `reservations:read` | | `reservation.completed` | The warranty ended without a refund. | `Reservation` | The agency the offer was made to. | `reservations:read` | | `reservation.refunded` | We refunded the fee after an accepted warranty claim. | `Reservation` | The agency the offer was made to. | `reservations:read` | | `reservation.cancelled` | The reservation was cancelled: not paid in time, or the accept was undone. | `Reservation` | The agency the offer was made to. | `reservations:read` | | `warranty_claim.created` | A warranty claim was filed on the reservation (API or portal). | `Reservation` | The agency the offer was made to. | `reservations:read` | | `data_export.ready` | A creator's data export that your app requested is ready. Fetch the download link with her token: `GET /v1/creator/data-export/{id}`. | `DataRequestRef` | The account that owns the OAuth app whose creator token requested the export. | `oauth_apps:manage` | | `job.completed` | An asynchronous job your app started finished (`succeeded` or `failed`). `GET /v1/jobs/{id}` with her token has the status and result. | `JobRef` | The account that owns the OAuth app whose creator token started the job. | `oauth_apps:manage` | | `deletion_request.completed` | Creator Guard carried out the deletion request your app sent: her data is anonymised and her login and grants are gone. Stop processing her data in your systems. | `DataRequestRef` | The account that owns the OAuth app whose creator token sent the deletion request (even though her grant no longer exists). | `oauth_apps:manage` | | `ping` | A test send (`POST /v1/webhook-endpoints/{id}/test`). | `{}` | Only the endpoint that was tested. | any key | "The account that owns the lead" is the partner account that submitted it. **Agency events** go only to the agency the offer was made to: `offer.created`, `offer.accepted`, `offer.declined`, `offer.expired`, `offer.retracted`, `offer.reopened` and `offer.progressed` (scope `offers:read`), `reservation.created`, `reservation.paid`, `reservation.completed`, `reservation.refunded`, `reservation.cancelled` and `warranty_claim.created` (scope `reservations:read`) — see [Agencies](https://docs.creator-guard.com/agencies/). **Creator API events** (`data_export.ready`, `job.completed`, `deletion_request.completed`, scope `oauth_apps:manage`) go to the account that owns the OAuth app whose creator token started the work. ## Reading events `GET /v1/events` lists the events of your key's mode, newest first, with `limit`, `starting_after` and `ending_before`. Filters: `type` (exact, or a group such as `lead.*`), `created_after`, `object` (the id of a lead, photo, commission, API key, webhook endpoint, offer, reservation, data request or job; confirmation events carry the lead id, warranty claims the reservation id). `GET /v1/events/{id}` reads one. Any key may call both. The list only contains events whose object the key may read — the scope in the table above: a key with only `leads:read` sees lead, photo and confirmation events but no commissions. Reading one event directly without that scope answers [`403 insufficient_scope`](https://docs.creator-guard.com/errors/#insufficient_scope); an unknown id, another account's event or one older than 30 days answers [`404 not_found`](https://docs.creator-guard.com/errors/#not_found). --- # SDKs & collections Source: https://docs.creator-guard.com/sdks/ Two thin clients and two collections for API tools. All four are generated from the [OpenAPI contract](https://docs.creator-guard.com/openapi.yaml), so every operation in the [API reference](https://docs.creator-guard.com/reference/) is in each of them, under its `operationId`. Neither client has runtime dependencies. The clients are not on npm or PyPI yet. Download them here and keep the copy in your project; the download always matches the contract version shown in the header. | Download | What | |---|---| | [creatorguard-python.zip](https://docs.creator-guard.com/downloads/creatorguard-python.zip) | Python client, Python 3.10 or newer, standard library only | | [creatorguard-typescript.zip](https://docs.creator-guard.com/downloads/creatorguard-typescript.zip) | TypeScript client (ES modules), Node 20 or newer | | [creatorguard.postman_collection.json](https://docs.creator-guard.com/downloads/creatorguard.postman_collection.json) | Postman collection (v2.1), one request per operation | | [creatorguard-bruno.zip](https://docs.creator-guard.com/downloads/creatorguard-bruno.zip) | Bruno collection with a `production` environment (`https://api.creator-guard.com`) | ## Python Unzip, then either copy `creatorguard.py` and `creatorguard_operations.py` next to your code or install the folder with `pip install ./creatorguard-python`. ```python import os from creatorguard import Client, CreatorGuardError cg = Client(os.environ["CG_API_KEY"]) lead = cg.create_lead(body={ "external_id": "crm-1047", "creator_name": "Mia", "instagram_handle": "@miacreates", "platforms": ["OnlyFans", "Instagram"], "consent_confirmed": True, }) for lead in cg.paginate("listLeads", query={"stage": "draft"}): print(lead["id"], lead["stage"]) ``` A creator integration (OAuth) passes the access token instead of a key: `Client(access_token=os.environ["CG_ACCESS_TOKEN"])`. Pass exactly one of the two; both are sent as `Authorization: Bearer …`. Every operation is also a method named after its `operationId` in snake case (`createLead` → `create_lead`). Path parameters are positional, everything else is a keyword: `query=`, `body=`, `idempotency_key=` (POST) and `if_match=` (PATCH and PUT). `cg.request("createLead", body=...)` does the same by name. ## TypeScript Unzip, build it once inside the folder with `npm ci && npm run build` (output in `dist/`), then install the folder in your project with `npm install ./creatorguard-typescript`. For a creator integration (OAuth) pass `accessToken` instead of `apiKey` — exactly one of the two. ```ts import { CreatorGuard, CreatorGuardError } from '@creatorguard/api'; const cg = new CreatorGuard({ apiKey: process.env.CG_API_KEY! }); const lead = await cg.request('createLead', { body: { external_id: 'crm-1047', creator_name: 'Mia', instagram_handle: '@miacreates', platforms: ['OnlyFans', 'Instagram'], consent_confirmed: true }, }); for await (const item of cg.paginate('listLeads', { query: { stage: 'draft' } })) { console.log(item); } ``` ## Retries and idempotency Both clients retry the same way, so a script behaves alike in either language: | Answer | Retried? | |---|---| | No answer (network error, timeout) | Yes | | `408`, `429`, `500`, `502`, `504` | Yes | | `503` | Yes, except `not_configured` | | `409 idempotency_in_progress` | Yes | | Any other `4xx` | No | Up to 2 retries by default (`max_retries` / `maxRetries`). The wait is the `Retry-After` header when the API sends one (at most 60 seconds), otherwise an exponential backoff from 0.5 to 8 seconds with jitter. A `Retry-After` longer than 60 seconds is never waited for: the call ends at once, without a retry, so a script cannot hang for an hour. For a `429` the client then raises `RateLimitError` with the wait in seconds (`retry_after` in Python, `retryAfter` in TypeScript) — schedule the next attempt yourself. A `429` that is still there after the last retry is a `RateLimitError` as well. Every `POST` carries an `Idempotency-Key`. The client makes one (a random UUID) unless you pass your own, and it reuses the same key for every retry of that call — so a lead that was created before a timeout is not created a second time. Pass your own key when your job can restart, for example the row id of your import. See [Idempotency & retries](https://docs.creator-guard.com/idempotency/). ## Pagination `paginate()` follows `next_cursor` as `starting_after` until `has_more` is `false` and yields the items one by one. Pass the filters of the list operation in `query`; `limit` sets the page size (1–100). ## Errors A non-`2xx` answer raises `CreatorGuardError` with `status`, `type`, `code`, `message`, `request_id`, `field` and `details` — the fields of the [error body](https://docs.creator-guard.com/errors/). Branch on `code`. A `429` is a `RateLimitError`, a subclass of `CreatorGuardError`. A proxy page instead of an API error (a `502` while a release switches over) has `code` `proxy_error`. When no HTTP answer arrives after the last retry, the Python client raises `ConnectionError_` and the TypeScript client `ConnectionError`. ## Webhook signatures Check `CG-Signature` against the raw request body (bytes, before any JSON parsing) and the endpoint secret. Both helpers accept every `v1` signature in the header (two during a secret rotation) and reject timestamps more than 300 seconds away from now. ```python from creatorguard import verify_webhook_signature def handle_webhook(raw_body: bytes, headers) -> int: if not verify_webhook_signature(raw_body, headers["CG-Signature"], os.environ["CG_WEBHOOK_SECRET"]): return 400 return 200 ``` ```ts import { verifyWebhookSignature } from '@creatorguard/api'; const header = String(req.headers['cg-signature'] ?? ''); if (!verifyWebhookSignature(rawBody, header, process.env.CG_WEBHOOK_SECRET!)) { res.status(400).end(); } ``` ## Postman and Bruno - **Postman:** Import → the JSON file. Put `api_key` into a Postman environment as a secret variable, not into the collection, which you might share. `base_url` is `https://api.creator-guard.com`. - **Bruno:** unzip, then Open Collection → the `creatorguard-bruno` folder. Pick the `production` environment and enter `api_key` there; it is a secret variable, so Bruno keeps it out of the files. There is one host for everything. To try requests without touching live data, use a `cg_test_` key: it works on the same `https://api.creator-guard.com` against your account's sandbox, see [Test mode](https://docs.creator-guard.com/test-mode/). A `cg_live_` key works on live data. Every `POST` request sends a fresh `Idempotency-Key` (`{{$guid}}`); a resend from the tool therefore counts as a new request. Request bodies are the examples from the reference. --- # Changelog Source: https://docs.creator-guard.com/changelog/ Newest first. Rules for version numbers: [Versioning](https://docs.creator-guard.com/versioning/). A version marked **unreleased** is merged but not live yet; it ships with the next production release, and its heading then gets the release date. The platform API continues the version numbers of the previous partner endpoint, which ended at 1.3.0; its history is at the end of this page. **Announced 11 November 2026:** Account e-mails (confirmation codes, password resets, invitations, security notices) will be sent through ALL-INKL.COM (Neue Medien Münnich, Germany), which already hosts our mailbox and domain name service, instead of Resend (Plus Five Five, Inc., USA). Resend then stops being a sub-processor ([Sub-processors](https://docs.creator-guard.com/legal/sub-processors/)). Sender: `noreply@creator-guard.com`. No change to the API, keys or webhooks. **5 November 2026:** Our database, logins and file storage moved from Supabase (USA) to our own server at OVHcloud in France. Supabase is no longer a sub-processor ([Sub-processors](https://docs.creator-guard.com/legal/sub-processors/)); the stopped copy it kept was deleted the same day. Everyone signs in once more; two-factor sign-in stays set up. No change to the API, keys or webhooks. ## 1.23.0 — unreleased (ships with the next production release) — Webhook scope on every send ### Tightened - **An endpoint's scope holds on every send, not only when an event is queued.** A delivery of an event the endpoint may no longer carry (its object type left the endpoint's scope, see [Webhooks](https://docs.creator-guard.com/webhooks/)) ends `failed` with `last_error: scope_removed` when it is next due, also when it was being sent at the moment the endpoint was narrowed. `POST /v1/webhook-endpoints/{id}/deliveries/{d}/retry` refuses such a delivery with [`409 invalid_state`](https://docs.creator-guard.com/errors/#invalid_state) (`current_state: scope_removed`). Effective with the production release of this version. ### Changed - **Our own failures end.** A delivery we cannot prepare (an internal error on our side, not your receiver's) is tried again with a growing pause, at most hourly; once it is past the 72-hour retry window it ends `failed` with `last_error: internal_error`. It does not count toward disabling your endpoint. A delivery whose 16 attempts are used up ends `failed` (`last_error: lease_expired`) instead of being sent a 17th time when our sender stopped during its last attempt. - **`deletion_request.completed` also when we delete her data outside the request.** If our team deletes or anonymises a creator's data for another reason while your app's deletion request for her is open, the request is completed and your account receives the event, as it would have for the request itself. ## 1.22.0 — unreleased (ships with the next production release) — No "lost" after payment ### Tightened - **A paid deal can no longer be marked lost.** `POST /v1/offers/{id}/mark-lost` works only from `accepted` before the placement fee was received; after that it answers [`409 deal_paid`](https://docs.creator-guard.com/errors/#deal_paid), from `accepted`, `contacted` and `in_talks` alike. A paid deal ends only through a warranty claim (`POST /v1/reservations/{id}/warranty-claim`) or Creator Guard. The agency portal follows the same rule. Effective with the production release of this version. ### Added - Error code `deal_paid` (409). ## 1.21.0 — unreleased (ships with the next production release) — Earnings of closed leads ### Changed - **Only a completed placement earns a commission.** `GET /v1/leads/{id}/earnings` answers `status: "void"` (amounts as before) for a lead that is lost, rejected or withdrawn and has no booked commission, instead of `expected`. A deal that completes after the agency reported it lost, or after the lead was closed, books no commission. Details: [Listing](https://docs.creator-guard.com/listing/). - Accepting an offer in the agency portal now follows the same rules as `POST /v1/offers/{id}/accept` (the current placement warranty terms, a vetted agency), and an accept can no longer be undone once the fee was received. No change to the API itself. ## 1.20.0 — 2026-10-17 — Agency vetting state ### Added - `vetting` on the agency profile (`GET /v1/agency-profile` and the answer of `PATCH /v1/agency-profile`), read-only: `status` (`registered`, `in_review` or `vetted`) and `waiting_matches`, the number of creators matched to your agency who wait for your vetting (a count only, nothing about them). Sending `vetting` in a `PATCH` is [`400 unknown_field`](https://docs.creator-guard.com/errors/#unknown_field). The sandbox (test keys) always reports `vetted` with `waiting_matches: 0`. ### Changed - **Offers reach an agency only after its vetting.** An agency account is ready at once, but offers with a creator's profile (and her listing, photos and offer events) reach it only once our 5-point vetting is done (`vetting.status: "vetted"`). A creator matched to an agency before that waits and is offered when the vetting is done. Details: [Agencies](https://docs.creator-guard.com/agencies/#offers). ## 1.19.0 — 2026-10-12 — Leads with just a name ### Changed - **`POST /v1/leads` needs only `creator_name` and `consent_confirmed: true`**, the same as a new creator in the partner portal. `platforms` and a contact (`instagram_handle` or `other_contact`) are optional now: a body without them no longer answers `400 missing_field` / `400 missing_contact`. Every field is still accepted and checked exactly as before when you send it (`platforms` at least one entry, an `instagram_handle` must be an Instagram profile, …), so keep sending everything you know. Without an `instagram_handle` there is no duplicate check by handle; send an `external_id` so a retry finds her again. - **`PATCH /v1/leads/{id}` may clear both contacts** (`instagram_handle` and `other_contact` set to `null`), as in the portal: it no longer answers `400 missing_contact`, a lead may end up without any contact. Every field you send is still checked as before (`creator_name` and `platforms` cannot be cleared). - `missing_contact` is now answered only by `PATCH /v1/creator/profile` (her own profile must keep a contact; unchanged). ## 1.18.0 — 2026-10-09 — The fee before review ### Tightened - **Submit for review needs the fee.** `POST /v1/leads/{id}/submit-for-review` and `POST /v1/creator/submit-for-review` answer [`422 not_ready_for_review`](https://docs.creator-guard.com/errors/#not_ready_for_review) with `fee_missing` in `error.blockers` while the lead has no `placement_fee` (or `0`); `next_actions.can_submit_for_review` is `false` until it is set. The portal and the Telegram bot follow the same rule. Leads our team added for your account are not affected and never show `fee_missing`. Creator tokens now see `fee_missing` in `next_actions.blockers` too: her referral partner still has to set the fee. ## 1.17.0 — 2026-10-08 — Leaked OAuth secrets and tokens ### Added - Leaked OAuth client secrets (`cgcs_`) and creator access and refresh tokens (`cgo_`, `cgr_`) are now revoked automatically when they turn up in public (GitHub secret scanning), like API keys: a leaked client secret is replaced by one nobody knows (roll a new one with `POST /v1/oauth-apps/{id}/roll`; a leaked previous secret stops working), a leaked token ends that creator's authorization. Details: [OAuth](https://docs.creator-guard.com/oauth/). - Audit actions `oauth_app.secret_leaked` and `oauth_app.token_leaked` in `GET /v1/audit-events` (actor `system`). ## 1.16.0 — 2026-10-08 — Data protection addendum ### Added - Agreement type `api_dpa`: the [data protection addendum](https://docs.creator-guard.com/legal/dpa/) for API partners (v1), for every account, with the EU Standard Contractual Clauses (Module One) for transfers to the USA. `GET /v1/me` (`terms`) and `GET /v1/agreements` list it after `api_terms`; `GET /v1/agreements/api_dpa/{version}` returns the text. Accept it once per account, by an owner or admin, in the portal (Settings → API) or with `POST /v1/agreements/api_dpa/accept`; the acceptance counts for live and test keys. Rules: [Authentication → Data protection addendum](https://docs.creator-guard.com/authentication/#data-protection-addendum). - Event `agreement.published` for `api_dpa` goes to every approved account, referral partners and agencies. - `terms_not_accepted` can name `agreement_type: "api_dpa"`. - The [sub-processors](https://docs.creator-guard.com/legal/sub-processors/) list is published. ### Tightened - With a **live key**, the actions that need the API Terms (creating or rolling a live key, registering a live OAuth app, every other write) also need the accepted data protection addendum: otherwise `403 terms_not_accepted` with `agreement_type: "api_dpa"` (`api_terms` is named first when both are missing). The same actions stay open as for the API Terms; test keys and creator access tokens are never checked. An account that held a live key when the addendum was published has **30 days** from the release to accept it (the date is shown in the portal); an account without a live key accepts it before its first one. ## 1.15.0 — 2026-10-08 — Search-profile match on offers ### Added - `match` on every offer (`GET /v1/offers`, `GET /v1/offers/{id}`, the offer actions, `POST /v1/test-helpers/offers` and the `offer.*` event payloads): how well she fits your search profile, checked with the same rules as our own matching. `score` counts the criteria met (a close match counts ½), `total` the criteria checked, `knocked_out` says a must-match criterion was missed (sort by `score` / `total`, knocked-out offers last), and `criteria` lists each one as `key` + `result` (`hit`, `near` or `miss`) + `must`. Only names and results, never her values: `niche` and `platforms` are only ever `hit` or `miss` (a close match within your tolerance shows as `hit` and counts as a full point in `score`). `null` without a search profile (or with nothing filled in) and while her listing is hidden. ### Changed - The offer `ETag` now also changes when your search profile changes, so a `PATCH` with an older `If-Match` answers `412` after you edit your search profile. - Every offer's `ETag` changes once when this version is deployed (it now includes the match). Read the offer again before a `PATCH` with `If-Match`. ## 1.14.0 — 2026-10-06 — Consent links shown once ### Changed - Consent links are stored only as hashes (like claim links), so a link is shown once, when it is made. `POST /v1/leads/{id}/consent-link` makes a **new** link on every call (valid at least 30 days). **Behaviour change (beta):** the lead's previous link can no longer be used to give consent — only to withdraw one, like an expired link (her confirmation page promises she can withdraw by opening her link again). Before, the call returned the same link and extended it, so call it only when you are about to send her the link. Two calls at the same moment each return a link; only the later one can give consent. - `consent.url` of a lead is set only in the `201` of `POST /v1/leads` that created it. A `200` (an existing lead returned), `GET /v1/leads/{id}` and an `Idempotency-Key` replay of the `201` answer `consent.url: null`; `consent.expires_at` keeps showing when her current link stops working. A `200` no longer extends that link. Links sent before this version keep working until they expire or a new one is made. ## 1.13.0 — 2026-10-06 — Offboarding OAuth apps ### Added - `enabled` and `disabled_reason` on every OAuth app (`GET`, `POST`, `PATCH /v1/oauth-apps…`). An app is disabled only by offboarding (`disabled_reason: member_offboarded`, `redirect_uris: []`): `/oauth/authorize` does not know it and `/oauth/token` answers `unauthorized_client` for codes and refresh tokens, without revoking anything. `PATCH /v1/oauth-apps/{id}` with `redirect_uris` enables it again. ### Changed - Removing a member (or lowering her role below admin) also removes every redirect URI of a live OAuth app that one of her keys added (`oauth_app.updated` by `system` in `GET /v1/audit-events`): open authorization codes issued to those URIs stop working, and a creator authorization whose current refresh token was issued through one of them is revoked (the creator connects the app again). An app left without redirect URIs is disabled. When you replace the list, only the URIs you add are recorded as yours; URIs registered before this version are not linked to any key and are not removed by offboarding. - Removing a redirect URI (yourself or through offboarding) also ends what was issued through it: an open authorization code for it fails at `POST /oauth/token` (`invalid_grant`), and a refresh token whose authorization went through it answers `invalid_grant` until the URI is registered again (nothing is revoked by this). Refresh tokens issued before this version are not affected. - The scopes a creator approves on the consent screen apply to her authorization when the app exchanges the code at `POST /oauth/token`, not already when she approves: until then her existing tokens keep the scopes they had. A code asking for a scope the app no longer has answers `invalid_scope`. - `Idempotency-Key` is now kept per API key (before: per account). A request repeated with another key of the same account runs anew instead of replaying the first key's answer. A retry sent with a key rolled in between is a new request as well. ## 1.12.0 — 2026-10-06 — API Terms of Use ### Added - Agreement type `api_terms`: the [API Terms of Use](https://docs.creator-guard.com/legal/api-terms/) (v1), for every account. `GET /v1/me` (`terms`) and `GET /v1/agreements` list it after your account's terms; `GET /v1/agreements/api_terms/{version}` returns the text. Accept it once per account, by an owner or admin, in the portal (Settings → API) or with `POST /v1/agreements/api_terms/accept`; the acceptance counts for live and test keys. Rules: [Authentication → API Terms](https://docs.creator-guard.com/authentication/#api-terms). - Event `agreement.published` for `api_terms` goes to every approved account, referral partners and agencies. - `terms_not_accepted` can name `agreement_type: "api_terms"`. ### Tightened - With a **live key**, creating or rolling a live key (`POST /v1/api-keys`, `POST /v1/api-keys/{id}/roll`, and in the portal), registering a live OAuth app (`POST /v1/oauth-apps`) and every other write need accepted API Terms: otherwise `403 terms_not_accepted` with `agreement_type: "api_terms"`. Reads, `DELETE /v1/api-keys/{id}`, `DELETE /v1/oauth-apps/{id}`, `DELETE /v1/webhook-endpoints/{id}`, `DELETE /v1/members/{id}` and `POST /v1/agreements/{type}/accept` keep working; test keys and creator access tokens are never checked. An account that held a live key when the API Terms were published has **30 days** from the release to accept them (the date is shown in the portal); an account without a live key accepts them before its first one. ## 1.11.0 — 2026-10-05 — Creator privacy for agencies ### Added - Event `offer.consent_revoked` (object `offer`, scope `offers:read`): the creator withdrew her consent to share her profile. It goes to every agency holding an offer for her, whatever the offer's status, so you can delete what you stored of her listing and photos. With it, an accepted offer whose reservation still awaits payment is retracted and that reservation cancelled (`offer.retracted`, `reservation.cancelled`); no reservation of hers can be paid while the withdrawal stands. Endpoints subscribed with `["*"]` receive it at once; an endpoint with a list of types receives it after you add it. ### Changed - While her consent is withdrawn, an offer's `listing` and `photo_count` are `null` and `GET /v1/offers/{id}/photos` answers `409 invalid_state` — for every offer status, unless your placement of her is `completed`. Her contact after payment is not affected. - The `creator.privacy` scope text on the consent screen now says that the app receives the copy of her data, including her support conversations. - Invitations to join an account are deleted 30 days after they were accepted, revoked or expired ([Data retention](https://docs.creator-guard.com/data-retention/)). ### Tightened - `creator_name` on offers (`GET /v1/offers`, `GET /v1/offers/{id}`, every offer action and the `data.object` of offer events) and on reservations (`GET /v1/reservations`, `GET /v1/reservations/{id}`, reservation events) is `null` until your agency paid for her (a reservation of yours for her that is `paid` or `completed`; `null` again after a refund). Identify her by `creator_ref` (`CR-…`) before that. The portal shows the creator number too. Sandbox offers follow the same rule (`…/mark-paid` shows the name). - `GET /v1/creator/data-export/{id}` and `GET /v1/jobs/{id}` (creator token) answer only the app that requested the export; another of her connected apps gets `404 not_found`. `POST /v1/creator/data-export` counts its one export per 24 hours per app. ## 1.10.0 — 2026-10-05 — Security review ### Added - Error code `referrer_app_not_allowed` (`403`). - `GET /v1/audit-events`: `agreement.accepted` when terms are accepted over `POST /v1/agreements/{type}/accept` (key, IP, type and version; accepting the same version again writes nothing). ### Changed - `POST /v1/members`: an address whose login cannot join any account now gets the same `201` invitation as any other address (it is listed, counts towards the 20 per 24 hours and has the same join page); it can never be accepted. Before it was `400 invalid_field` `email`. - `POST /v1/leads/{id}/consent-link`: an `Idempotency-Key` replay answers `url: null` (the link is never stored); call again for a link. - `DELETE` requests ignore `If-Match` (no `DELETE` operation documents it); a malformed `If-Match` on a `DELETE` is no longer a `400`. - Requests refused before any work for a limit (`429 rate_limited`, `429 concurrency_limited`) no longer appear in `GET /v1/request-logs` and `GET /v1/usage`; they never counted towards the rate limit. `403 ip_not_allowed` still appears there (so you see a key used from outside its allow-list) and still does not count towards the rate limit. - Removing a member (or lowering her role below admin) replaces the client secret of every OAuth app whose current or still-accepted previous secret was set by one of her keys (`oauth_app.secret_rolled` by `system`); roll it to see the new one. - `POST /oauth/token`, `POST /oauth/revoke`, `GET /oauth/authorize` and the consent decision share the per-IP budget of requests without an account: over it, `429` with `Retry-After`. Successful token and revoke calls do not spend it. ### Tightened - Creator API: `POST /v1/creator/consent/grant`, `POST /v1/creator/age-confirmation` and `POST /v1/creator/agreements/{type}/accept` with a token of an OAuth app owned by the account that referred her → `403 referrer_app_not_allowed`. She gives her consent, 18+ confirmation and terms only on Creator Guard (consent link or creator portal). Withdrawing consent and reading her consent state are unchanged. - A member who joined through an invitation made by an API key cannot create or roll portal keys that are less restricted than that key: they get its IP allowlist and expire no later than it does. ## 1.9.0 — 2026-10-05 — Team members ### Added - `GET /v1/members`, `POST /v1/members` and `DELETE /v1/members/{id}` (scope `members:manage`): the people of an account with their roles (`owner`, `admin`, `developer`, `viewer`) and `email_verified` (`false` for a login created on the join page), invitations for `developer` or `viewer` with a one-time join link (`join_url`, valid 48 hours, shown once — `join_url: null` in an `Idempotency-Key` replay; inviting an address again replaces its open invitation; an address whose login cannot join any account is `400 invalid_field` `email`; at most 20 attempts per 24 hours, `409 limit_reached`), removal and revocation; the owner answers `409 invalid_state` with `current_state: owner`. Removing a person also revokes their open invitations and every API key whose secret they had, and disables webhook endpoints whose signing secret they know (new secret, roll it to see it). Live keys only (a `cg_test_` key gets `404 not_found`). Changes appear in `GET /v1/audit-events` as `member.invited`, `member.joined`, `member.role_changed`, `member.removed` and `member.invitation_revoked`. - Key scope `members:manage`, selectable for new keys in the portal and over `POST /v1/api-keys`. ### Tightened - A rolled key in its grace period can no longer use `members:manage` or `oauth_apps:manage` (as before `keys:manage` and `webhooks:manage`): `403 insufficient_scope`. - In the portal, a member with the developer role creates, rolls and revokes only keys with read scopes, `keys:manage`, `webhooks:manage`, `usage:read` and `audit:read`. ## 1.8.0 — 2026-10-05 — Creator API, OAuth and claim links ### Added - `POST /v1/leads/{id}/claim-link` (`leads:write`): a single-use link (7 days) where she chooses her own email and password for the creator portal; a new link replaces the open one. The URL is shown once (`url: null` in an `Idempotency-Key` replay). `409 invalid_state` with `current_state` `claimed`, `withdrawn` or `rejected`. - Key scope `oauth_apps:manage` (OAuth apps that creators sign in to with Creator Guard), selectable for new keys in the portal and over `POST /v1/api-keys`. - OAuth apps (`oauth_apps:manage`): `GET` and `POST /v1/oauth-apps`, `GET`, `PATCH` (with `If-Match`) and `DELETE /v1/oauth-apps/{id}`, `POST /v1/oauth-apps/{id}/roll`; the `oauth_app` object. At most 10 apps per mode; the client secret of a confidential app is shown once (`client_secret: null` in an `Idempotency-Key` replay), a roll keeps the previous secret valid for 24 hours; deleting an app revokes every creator's grant to it. Changes appear in `GET /v1/audit-events` as `oauth_app.created`, `oauth_app.updated`, `oauth_app.deleted` and `oauth_app.secret_rolled`. - OAuth 2.1 authorization server on `https://app.creator-guard.com` for the apps above: `GET /oauth/authorize` (hosted sign-in and consent screen, authorization code with PKCE `S256`, live apps only), `POST /oauth/token` (`authorization_code`, `refresh_token` with rotation; a reused code or refresh token ends the whole grant), `POST /oauth/revoke` (RFC 7009) and the metadata document `/.well-known/oauth-authorization-server` (RFC 8414). Browser apps may read token and revocation answers only from the origin of one of their registered redirect URIs. - `POST /v1/test-helpers/oauth-codes` (`oauth_apps:manage`, test keys only): an authorization code for a test-mode app and a sandbox lead, as if the creator had clicked "Allow"; valid for 60 seconds, exchanged at `/oauth/token`. An `Idempotency-Key` is ignored (a code is single-use). - Creator endpoints for a creator's OAuth access token (security scheme `creatorToken`, scopes `creator.profile:read`, `creator.profile:write`, `creator.photos:write`, `creator.consent:write`, `creator.support`, `creator.privacy`): `GET /v1/creator/me`; `GET` and `PATCH /v1/creator/profile` (with `If-Match`; never fees, deal terms or `of_verified`); `POST /v1/creator/submit-for-review`; `GET` and `POST /v1/creator/photos` (metadata removed on our side), `DELETE /v1/creator/photos/{photo}`; `GET /v1/creator/consent-text`, `GET /v1/creator/consent`, `POST /v1/creator/consent/grant`, `…/revoke` and `POST /v1/creator/age-confirmation` (consent ledger entries with channel `oauth_app:app_…`; a grant needs the current text version, a withdrawal never fails because of it; a grant also records her 18+ confirmation like the hosted consent page and is `409 invalid_state` with `current_state` `age_declined` / `age_pending` while her 18+ check is declined or under review); `GET /v1/creator/agreements`, `POST /v1/creator/agreements/creator_terms/accept`; `/v1/creator/support-tickets` (list, open, messages, reply, close); `POST /v1/creator/data-export` (`202` + job) and `GET /v1/creator/data-export/{id}` (a new download link of at most 1 hour on every call while the export is kept, 7 days); `POST /v1/creator/deletion-request`; `GET /v1/creator/connected-apps` and `DELETE /v1/creator/connected-apps/{app}` (the calling app's own grant only; `DELETE` needs `creator.profile:write`). An account API key on these is `403 wrong_account_type`. - `GET /v1/jobs/{id}`: asynchronous jobs (the data export); the `job`, `data_request`, `creator`, `creator_profile`, `consent_state`, `consent_text`, `creator_agreement`, `support_ticket`, `support_message` and `connected_app` objects. - Events `data_export.ready`, `job.completed` and `deletion_request.completed` for the account that owns the OAuth app which acted for the creator (objects `data_request` and `job`, read with `oauth_apps:manage`). `data.object` is a reference (`{"id": "dreq_…", "object": "data_request"}`, `{"id": "job_…", "object": "job"}`), never her data; the schemas `DataRequestRef`, `JobRef`, `DataRequestEvent` and `JobEvent`. A webhook endpoint set up before 1.8.0 receives them only after its event types are changed in the portal or with a key that holds `oauth_apps:manage` (OAuth apps exist only from 1.8.0 on). - `GET /v1/events?object=` also takes `dreq_…` and `job_…` ids. - `x-oauth` on the `creatorToken` security scheme: issuer, metadata and revocation URLs, PKCE methods, client authentication methods and the lifetimes of codes, tokens and a rolled client secret. - Guides in the new section "Creators": [OAuth for creator dashboards](https://docs.creator-guard.com/oauth/), [Creator API endpoints](https://docs.creator-guard.com/creator-api/), [Consent ledger](https://docs.creator-guard.com/consent-ledger/) and [Hosted pages for creators](https://docs.creator-guard.com/hosted-pages/) (consent link, claim link, creator portal). ### Changed - The error codes `invalid_token`, `expired_token` and `consent_text_outdated` are now answered (creator endpoints); `account_not_active` also answers a creator token while the account that owns the app is not approved (her grant stays). A withdrawal of consent never fails with `consent_text_outdated`. - `DELETE /v1/leads/{id}/photos/{photo}`: the photo is removed first and its file after; if removing the file fails, the photo is put back and the answer is `502 upstream_failed` as before (no photo can lose its file when the listing goes live at the same moment). - Hosted consent link: after its 30 days it can no longer give consent, but it still withdraws a consent given through it. ## 1.7.0 — 2026-10-05 — Agency API ### Added - **Agency endpoints** for agency keys: `GET` and `PUT /v1/search-profile` (incl. `flex`), `GET` and `PATCH /v1/agency-profile`, `GET /v1/offers`, `GET` and `PATCH /v1/offers/{id}`, `GET /v1/offers/{id}/photos`, the actions `accept`, `decline`, `undo-accept`, `mark-contacted`, `mark-in-talks`, `mark-signed` and `mark-lost`, `GET /v1/reservations`, `GET /v1/reservations/{id}`, `POST /v1/reservations/{id}/warranty-claim` and `GET /v1/reservations/{id}/creator`. A referral partner's key gets `403 wrong_account_type` on them (checked before the scope). Guide: [Agencies](https://docs.creator-guard.com/agencies/). - Accepting an offer needs the current `warranty_terms`; without them `403 terms_not_accepted` names `agreement_type: "warranty_terms"`. - Events `offer.created`, `offer.accepted`, `offer.declined`, `offer.expired`, `offer.retracted`, `offer.reopened`, `offer.progressed`, `reservation.created`, `reservation.paid`, `reservation.completed`, `reservation.refunded`, `reservation.cancelled` and `warranty_claim.created` (objects `offer` and `reservation`, read with `offers:read` and `reservations:read`). - Test helpers `POST /v1/test-helpers/offers`, `POST /v1/test-helpers/reservations/{id}/mark-paid`, `…/complete` and `…/refund`, and `POST /v1/test-helpers/clock/advance` (test keys only). `POST /v1/test-helpers/reset` leaves an agency's test offers and reservations in place (known limit). - The scopes `offers:read`, `offers:write`, `reservations:read`, `reservations:write` and `search_profile:write` are accepted again, now that their endpoints exist. Agency keys issued by Creator Guard carry them plus `account:write`. - Error codes `offer_taken`, `offer_expired`, `listing_unavailable`, `payment_pending`, `undo_window_passed`, `claim_exists` and `warranty_expired` are now answered by the agency endpoints. ## 1.6.0 — 2026-10-05 — Consent link in the lead ### Added - `consent` on the lead returned by `POST /v1/leads` (`201` and `200`) and `GET /v1/leads/{id}`: `status` (`pending`, `granted`, `revoked`), `url` (her personal consent page) and `expires_at`. Creating a lead makes the link or extends it to at least 30 days, like `POST /v1/leads/{id}/consent-link`; reading a lead never extends it. `url` and `expires_at` are `null` after her data was erased at her request. Lists, `PATCH`, withdraw and event payloads do not carry it. ## 1.5.0 — 2026-10-05 — Webhooks, photos, keys and test mode ### Added - Test mode: `cg_test_` keys work on a sandbox with the same URLs; every limit is halved. Test helpers `POST /v1/test-helpers/leads/{id}/confirm`, `…/approve-listing`, `…/reject`, `POST /v1/test-helpers/commissions/{id}/mark-paid` and `POST /v1/test-helpers/reset`; sandbox files under `GET /v1/test-files/{path}`. - API keys: `GET` and `POST /v1/api-keys`, `POST /v1/api-keys/{id}/roll` (grace period 0–72 hours), `DELETE /v1/api-keys/{id}`; the `api_key` object; key self-service and key policies in the portal. - Webhooks: `/v1/webhook-endpoints` (list, create, get, change with `If-Match`, delete), `…/roll` (new signing secret, 24 hours of overlap), `…/test`, `…/replay`, `…/deliveries` and `…/deliveries/{d}/retry`; signed deliveries (`CG-Signature`), retries for 72 hours, egress IP 187.127.76.75. - Events: `GET /v1/events` and `GET /v1/events/{id}` (30 days); 17 event types, documented as OpenAPI `webhooks`. - `version` on leads, photos and commissions; `sequence` on events. - Photos: `GET` and `POST /v1/leads/{id}/photos` (multipart upload, metadata removed on our side), `PATCH` and `DELETE /v1/leads/{id}/photos/{photo}`; `lead`, `created_at` and `version` on the photo object. - Earnings: `GET /v1/commissions`, `GET /v1/commissions/{id}` (`?expand=lead`), `GET /v1/payout-details` (masked). - Account: `PATCH /v1/me`, `PUT` and `DELETE /v1/me/logo`. - `POST /v1/extract`: lead and listing fields suggested from text; nothing stored. - Observability: `GET /v1/request-logs`, `GET /v1/usage`, `GET /v1/audit-events` (incl. `account.mfa_enabled` / `account.mfa_removed` when an authenticator is set up or removed). - `?fields=` on every `GET` that answers JSON. - Error codes `limit_reached` (409, with `error.limit`) and `upstream_failed` (502; also on photo and logo delete when the file cannot be removed — nothing changes then). - Uploads (photos, logo): one at a time per key → otherwise `429 concurrency_limited`. - Keys made or rolled over the API inherit the calling key's IP allowlist and expiry (`400 invalid_field` on `ip_allowlist` outside it). - Webhook replay: at most 1,000 open deliveries per endpoint (`409 limit_reached`), 10 replays per account and day; deliveries are shared fairly between endpoints (at most 5 at once per endpoint). - Webhook endpoints carry only the events the key that set them up may read (`403 insufficient_scope` for other event types). - `GET /v1/audit-events` answers in the mode of the key (a test key sees only test-mode events). - A rolled key in its grace period can no longer use `keys:manage` or `webhooks:manage` (`403 insufficient_scope`). ### Tightened - `DELETE /v1/api-keys/{id}` needs every scope of the key it revokes (`403 insufficient_scope`), like roll. - Keys carry only the scopes of endpoints that exist: `offers:*`, `reservations:*`, `search_profile:write`, `oauth_apps:manage` and `members:manage` are no longer accepted (`400 invalid_field` on `scopes`); they come back with their endpoints. ## 1.4.0 — 2026-10-05 — Platform API (beta) ### Added - New API at `https://api.creator-guard.com/v1/`, in beta. Its version numbers continue after the previous endpoint's 1.3.0. - Keys with scopes, optional expiry and IP allowlist; `GET /v1/me`. - Agreements: list, read, accept. Option lists and brokerage settings. - Leads: create (optionally with listing), list with filters and cursors, get with `expand`, update, withdraw. - Listing: read and update, submit for review, confirmations, consent link, timeline, earnings. - `Idempotency-Key` on every `POST`, `ETag` / `If-Match`, `RateLimit` headers, `X-Request-Id`, one error format with `details` and `doc_url`. ### Removed - The previous endpoint `POST https://creator-guard.com/api/partner/v1/leads` and its documentation. It had no users; its history (1.0.0 to 1.3.0) is below. --- # Versioning Source: https://docs.creator-guard.com/versioning/ The API follows [semantic versioning](https://semver.org/): - **The major is in the URL.** `/v1/` is major version 1. A change that could break a working integration never ships inside `v1`; it ships as `/v2/`. - **The full version is `MAJOR.MINOR.PATCH`**, for example `1.6.0`: `info.version` in [`/openapi.yaml`](https://docs.creator-guard.com/openapi.yaml), the heading of each [changelog](https://docs.creator-guard.com/changelog/) entry and the `X-API-Version` header of every answer. Log it with your requests. - **The numbers continue** after `1.3.0`, the last version of the retired partner endpoint `POST /api/partner/v1/leads`: this API started at `1.4.0`. That endpoint's history is at the end of the [changelog](https://docs.creator-guard.com/changelog/). ## What changes the version | Change | Version | |---|---| | Clearer docs; a fix that makes the API do what the docs already said | **PATCH** (`1.6.0` → `1.6.1`) | | Something added: an optional request field, a response field, an endpoint, a scope, an error code for a new situation | **MINOR** (`1.6.0` → `1.7.0`) | | Stricter validation within v1 (below) | **MINOR** with a **Tightened** entry | | Anything that can break a working integration | **new major** (`/v2/`) | Breaking: removing or renaming a field, a new *required* request field, accepting fewer values for a field, removing an error code or status, a different code for an existing situation, a changed type, authentication or base URL. Read answers tolerantly: ignore fields, headers and enum values you do not know, and treat an unknown `error.code` by its HTTP status. That is what lets us add things within v1. ## Beta The platform and the API are in **beta**. The rules on these pages are binding, and the contract check below still blocks breaking changes inside `/v1/`. What beta means: features arrive often, and validation can be tightened without notice. ## Stricter validation within v1 Sometimes the API accepts input it cannot handle well. Rejecting it is stricter, but it protects your data rather than changing what a correct integration sends. Such a change ships as a **MINOR** release and is **effective at release**. Its changelog entry under **Tightened** says exactly what is now rejected and with which error; there is no separate email. The same applies, rarely, to data protection on the answer side: a response field may become `null` in situations where we may no longer show it (for example `creator_name` on offers before payment, 1.11.0). The field stays in every answer; the spec marks it with `x-nullable-since` and the **Tightened** entry says when it is `null`. ## API Terms of Use The legal rules for using the API are the [API Terms of Use](https://docs.creator-guard.com/legal/api-terms/), a versioned agreement of its own (`api_terms`), separate from this contract versioning. A new version is announced with the event `agreement.published` and in the changelog. A material change that is worse for you takes effect **30 days** after we publish it; a change required by law, or needed for security or to stop abuse, takes effect on publication. Accepting the terms is described under [Authentication → API Terms](https://docs.creator-guard.com/authentication/#api-terms). ## Retiring a major When `/v2/` goes live, `/v1/` stops on the same day: every request answers [`410 version_sunset`](https://docs.creator-guard.com/errors/#version_sunset), with `Deprecation`, `Sunset` and `Link` headers pointing to the migration guide. There is no notice period, so watch the [changelog](https://docs.creator-guard.com/changelog/). ## How we keep to this The published contract is checked automatically before every release against the last recorded version: an addition needs a MINOR version, stricter validation needs a **Tightened** entry, and a breaking change cannot be released under `/v1/` at all. --- # Support Source: https://docs.creator-guard.com/support/ ## Where to ask - **On Telegram:** [@creatorguardsupport](https://t.me/creatorguardsupport), our support account. - **In the partner or agency portal**, the **Support** button: it opens your own Telegram support group if one is set up for you, otherwise our Telegram support. - **By email:** [info@creator-guard.com](mailto:info@creator-guard.com). Our support never asks for your password, a login code or a full API key, on Telegram or anywhere else. Anyone who does is not us. ## What to include - The **`request_id`** (`req_…`) of the request — from the error body or the `X-Request-Id` header. With it we find the request in our log. - The **creator number** (`CR-1047`) or your `external_id` when the question is about a creator. - The HTTP status and the error `code`. - Your key's **prefix** (`cg_live_ab12`, as shown under **Settings → API**) when the question is about a key. Never send the full API key, not even to us. We never need it. ## Common requests | You want to… | Do this | |---|---| | Get a key, another scope or an IP allowlist | Ask us. The key is handed over once, through a secure channel. | | Revoke a key that may have leaked | Tell us right away. It stops working on the next request. | | Higher limits for an import | Tell us the volume and timing before you start. | | Know why a creator returned `409` | Send us the handle. We do not reveal the other account, but we check that nothing went wrong. | | A webhook endpoint that was disabled | Fix the receiver, then re-enable it: [Webhooks](https://docs.creator-guard.com/webhooks/#retries). | --- # Reporting a security vulnerability Source: https://docs.creator-guard.com/security/ If you believe you have found a security vulnerability in a Creator Guard website, the platform or the partner API, please tell us. We read every report. ## How to report Email **info@creator-guard.com** with the subject "Security". Please include: - what you found and where (the URL or the API endpoint), - the steps to reproduce it, - what an attacker could do with it, - how we can reach you with questions. Do not put personal data of creators, agencies or partners into your report. If you came across such data, say so, but do not copy it. Please write in English. ## Scope - `creator-guard.com` — the website in every language - `app.creator-guard.com` — the portals and the admin - `api.creator-guard.com` — the partner API (`/v1`) and the webhooks we send - `docs.creator-guard.com` — this documentation ## Out of scope - Denial-of-service and load tests, and automated scans that send large amounts of traffic. - Social engineering of our team, partners, agencies or creators, and physical attacks. - Services of third parties we use (for example our database or email provider): report those to the provider. - Findings without a demonstrated security impact: missing headers on static pages, clickjacking on pages without actions, version banners, self-XSS, rate limits on requests that change nothing. - An API key you found in public: it is revoked as soon as it is reported to us (see [Authentication](https://docs.creator-guard.com/authentication/#leaked-keys)). Tell us where you found it. ## While you test - Use only your own account and your own test data. Never read, change or delete data that is not yours; if you see someone else's data, stop and report. - Use test-mode keys (`cg_test_`) whenever you can. - Do not contact creators, agencies or partners. - Do not make the issue public before we have fixed it. We will tell you when the fix is live. ## What happens next We confirm your report within 3 business days and keep you updated until the issue is fixed. If you act in good faith and follow this policy, we will not take legal action against you or ask anyone else to, and we consider your research authorised. We do not run a paid bug bounty programme. With your permission we thank you by name in our changelog. --- # API Terms of Use (v1) Source: https://docs.creator-guard.com/legal/api-terms/ **Effective:** upon publication · **Applies to:** every use of the Creator Guard API by your account from publication on — live keys, test keys, webhooks, OAuth apps and the client libraries — in addition to the terms you accepted for your account. ## In plain words (summary — the numbered sections govern) The API is a second door into the same platform: everything your Account Terms say about creators, leads, offers, fees and data applies to what you do through it. Keep your keys secret; whatever happens with your keys is your responsibility, and a key that leaks is revoked at once. Stay within the published limits and do not try to get around them. Use creator data only for the placement it was shared for — no scraping, no reselling, no catalogues, no AI training. An app a creator connects must show her who you are and must never speak for her. The API is in beta: the published service levels are targets, not guarantees, and the versioning rules on docs.creator-guard.com are the ones we keep. API access is free. Changes to these terms that are worse for you take effect 30 days after we publish them. If you abuse the API we can switch your access off. ## 1. Definitions and document hierarchy 1. **"API"** means the Creator Guard platform API at `https://api.creator-guard.com/v1` and its later major versions, including the sandbox reached with test keys, webhooks we send to your servers, the OAuth authorization server at `https://app.creator-guard.com`, the client libraries and collections we publish, and the documentation at docs.creator-guard.com (the **"Docs"**). 2. **"Account Terms"** means the terms your account accepted on the Platform: the Referrer Terms for referral partner accounts; the Agency Platform Terms and the Placement Warranty Terms for agency accounts. Capitalized terms not defined here have the meaning given there. 3. **"Key"** means an API key (`cg_live_…` or `cg_test_…`), a webhook signing secret (`whsec_…`), an OAuth client secret, and any OAuth access or refresh token issued to your app. **"Creator Data"** means any information about a Creator that you send to or receive from the API. 4. **Hierarchy.** These API Terms supplement the Account Terms and do not replace them. For keys, limits, versioning, the sandbox, webhooks and OAuth apps these API Terms prevail. For everything else — leads, offers, fees, Commissions, the evaluation license, conduct, anti-circumvention and the use of Creator Data — the Account Terms prevail; for placement remedies the Placement Warranty Terms prevail. Where these API Terms add a restriction on top of the Account Terms, both apply. On data protection, the data protection addendum for API partners (published in the Docs) prevails once it is concluded. 5. The Docs describe how the API works and the limits in effect. Where the Docs and these API Terms differ on a legal point, these API Terms prevail. ## 2. Who may use the API 1. Creator Guard, operated by Creator Guard LLC (1209 Mountain Road Pl NE #11622, Albuquerque, NM 87110, USA), grants your account a non-exclusive, non-transferable, revocable right to use the API for the duration of your account, solely to perform the Account Terms: as a referral partner to submit and manage your own leads and see your Commissions; as an agency to receive and handle Offers and Reservations; and, through an OAuth app, to act for a Creator who connected your app, within the scopes she allowed. 2. Access follows your account. Keys work only while your account is approved; while it is pending or disabled, the API refuses your requests. 3. You may not sublicense, sell, rent or otherwise give access to the API, a Key, or API output to anyone outside your organization. Contractors who build or run your integration may use your Keys on your behalf; you are responsible for them as for yourself, and the limits of the Account Terms on sharing Creator Data apply to them unchanged. ## 3. Keys and credentials 1. **Secrecy.** Keep every Key secret: on servers only, never in a browser, a mobile or desktop app you ship, a public repository, a support message, or a chat. A Key is sent only to `https://api.creator-guard.com` (an OAuth secret or token only to the endpoints the Docs name for it). 2. **Responsibility.** Every request made with one of your Keys is treated as made by your account, whoever sent it. You are responsible for everything done with your Keys until they are revoked. 3. **Report a leak.** If a Key may have been exposed, revoke or roll it at once (in the portal or with the API) and tell us without undue delay at info@creator-guard.com, naming the Key's prefix — never the full Key. 4. **Our right to revoke.** We may revoke any Key immediately and without asking first when it is reported to us as public — by you, by anyone else, or by an automated secret scanner such as GitHub's — or when we reasonably believe it is compromised or used against these API Terms. A revoked Key cannot be re-enabled; you create a new one. We tell your account's contact address when we revoke a leaked Key. 5. Use the security features the Docs offer where they fit your setup (scopes, IP allowlists, expiry dates, the key policy). Give each Key only the scopes it needs. ## 4. Team members and roles 1. Your account may have several members with the roles the Docs describe (owner, admin, developer, viewer). You decide who becomes a member and with which role, and you are responsible for what every member and every Key a member created does. 2. Remove a member without delay when the person leaves your organization or no longer needs access. Removing a member or lowering their role revokes the Keys and rotates the secrets the Docs list for that case; it does not undo what was done before. 3. A login belongs to one person. Do not share logins or second factors between people. ## 5. Permitted and prohibited use 1. **Permitted.** You may use the API to automate what your Account Terms allow you to do in the portal, for your own account and your own leads, Offers and Reservations. 2. **Prohibited.** You must not, and must not let anyone else: (a) **scrape or harvest** — use the API, the portal or the hosted pages to collect data beyond what your account needs for its own leads, Offers and Reservations, or to compile lists, databases or "catalogues" of Creators, agencies or referral partners; (b) **probe for other accounts' creators** — submit handles you do not genuinely represent to find out whether another account already submitted a Creator, or otherwise try to learn which account referred a Creator or which agencies saw her; (c) **circumvent limits** — exceed or evade the rate limits, the concurrency limits, the duplicate budget or any other limit, for example by spreading load over several Keys or accounts, rotating IP addresses, or retrying refused requests in a tight loop; (d) **resell or share access** — give access to the API, a Key or API output to a third party, or offer a service that lets others use the API through you; (e) **use Creator Data beyond its purpose** — keep, combine, enrich, publish, forward, advertise with, or use for training AI models or creating AI-generated likenesses, any Creator Data you receive, beyond what the Account Terms allow; (f) **impersonate** — build an OAuth app, a hosted flow or any screen that presents itself as the Creator, as Creator Guard, or as another account, or that collects a Creator's Creator Guard password; (g) **record a Creator's decisions for her** — give, or route around the block on, her consent, her 18+ confirmation or her acceptance of the Creator Terms through an app of the account that referred her. These decisions are made only on Creator Guard's own pages, and the API refuses them through the referring account's apps (`403 referrer_app_not_allowed`). Using another account's app, a contractor's app or any other workaround for that purpose is a material breach; (h) **attack the API** — run load or denial-of-service tests, send automated vulnerability scans with large volumes of traffic, try to reach data of another account, or bypass authentication, scopes or IP allowlists; (i) **put real Creator Data into the sandbox** — test keys are for made-up data only; (j) send data you are not allowed to send, or content that is unlawful, or put identity documents, passwords, payment details or explicit material into free-text fields. 3. Prohibited use under Section 5(2)(b), (e), (f) or (g) is also a breach of the Account Terms and is sanctioned under them. ## 6. OAuth apps 1. You may register OAuth apps through which a Creator can connect her Creator Guard account to your service. An app may act for her only within the scopes she allowed, and only while the relationship the Docs require (you referred her, or you hold a paid Reservation for her) exists. 2. Your app must name your organization truthfully, link to your own privacy policy, and use a name and logo that do not suggest it is Creator Guard or someone else. 3. Before your app records a decision of hers that the Docs allow it to record, show her the current text we provide, unchanged, and send its version with her answer. Her withdrawal of consent must always be possible through your app. 4. When she disconnects your app, or the relationship ends and we revoke her grant, stop acting for her. What you hold about her from that point is governed by the Account Terms and Section 9. ## 7. Limits, fair use and throttling 1. The limits in effect for your account are those published in the Docs (rate limits per Key, concurrency, uploads, webhook replays, and the duplicate budget of the account) or shown by `GET /v1/me`. Test keys have the reduced limits the Docs name. We may set different limits for your account; the API shows them. 2. **Fair use.** Use the API with reasonable restraint: no requests your integration does not need, no polling where events or webhooks serve, and tell us in advance before a large import. 3. We may throttle, queue or refuse requests — including with `429` answers — to protect the API, other accounts or Creators, and may lower your limits if your use strains the API or breaches Section 5. Where it is practical we tell you first. ## 8. Beta, service levels, changes and deprecation 1. **Beta.** The Platform and the API are in beta. Features arrive often. The versioning rules published in the Docs ("Versioning") are binding on us. 2. **Service levels are targets.** The service levels published in the Docs (today: 99.5 % monthly availability of `/v1` in live mode, p95 under 500 ms for single-resource reads, p95 under 60 seconds to the first webhook delivery attempt) are targets we run the API against and measure. They are not a guarantee, and no service credits or other remedies attach to them, unless we agree otherwise in writing. 3. **Changes within a major version.** A change that could break a working integration never ships inside a major version (`/v1`); it ships as a new major. We may add to a major version at any time (fields, endpoints, scopes, error codes, events); read answers tolerantly as the Docs describe. Stricter validation within a major version — rejecting input the API cannot handle well, or returning `null` in a field we may no longer show — ships as a minor release, is effective at release, and is described in the changelog under "Tightened"; there is no separate e-mail. 4. **Retiring a major version.** When a new major version goes live, the previous one stops on the same day: its requests answer `410 version_sunset`. There is no notice period; watch the changelog. 5. We may change, suspend or discontinue any part of the API, the sandbox, the client libraries or the Docs, within the rules of this Section. ## 9. Data protection 1. **Roles.** Each party's role for the Creator Data exchanged through the API follows the Account Terms and, once concluded, the data protection addendum for API partners. Until then, and as the working basis of that addendum, you and we each act as an independent controller for the Creator Data each of us holds: you for what you collect and keep in your systems, we for what we receive and process for the Platform. 2. **Your own systems.** Protect Creator Data in your systems with measures appropriate to its sensitivity — a Creator's age and content categories can reveal information about her sex life. Webhook endpoints must use HTTPS and check our signature as the Docs describe. 3. **Agencies.** Creator Data an agency receives through the API or webhooks is licensed only to evaluate and complete a placement (Agency Platform Terms, Section 5). The Creator's name and contact details are released only after we confirm receipt of the Placement Fee; before that the API shows her creator number only (`creator_name` is `null`). Delete what you received about a Creator within 30 days after an Offer ends without your payment for her, and within 30 days after we tell you she withdrew her consent (the event `offer.consent_revoked`), unless you completed a placement with her; after Contact Release, Section 9 of the Agency Platform Terms governs. 4. **Referral partners.** Send only Creator Data the Creator knows you are sending (Referrer Terms, Sections 2 and 6), and forward a Creator's request about our copy of her data to info@creator-guard.com with her creator number. 5. **OAuth apps.** Creator Data your app receives because a Creator connected it is processed under your own privacy policy, which your app names; for that copy you are an independent controller. 6. **What we log.** We keep a request log, usage statistics and an audit trail of changes to your account, for the periods published in the Docs ("Data retention"), and use them to run, secure and support the API. ## 10. Security 1. Report a vulnerability you find in the API, the Platform or the Docs to info@creator-guard.com with the subject "Security", following our vulnerability disclosure policy at https://docs.creator-guard.com/security/ (machine-readable contact: https://docs.creator-guard.com/.well-known/security.txt). 2. Test only with your own account, your own test data and, where possible, test keys. Never read, change or delete data that is not yours; if you see someone else's data, stop and report it. Do not make an issue public before we fixed it. 3. Tell us without undue delay of any security incident in your systems that affects Creator Data received through the API or a Key — without undue delay and at the latest within 72 hours after you become aware of it, at info@creator-guard.com. ## 11. Suspension and termination 1. We may suspend your API access, or parts of it, immediately and without prior notice where we reasonably believe it is needed to stop a breach of Section 3, 5 or 6, to protect Creators, other accounts or the API, or where the law requires it. Other breaches follow the sanctions ladder of the Account Terms. 2. **Effects.** On suspension or termination we may revoke your Keys, disable your webhook endpoints, disable or delete your OAuth apps (which ends the Creators' connections to them) and refuse further requests. Suspension of your account under the Account Terms suspends your API access as well. 3. You may stop using the API at any time by revoking your Keys and deleting your webhook endpoints and OAuth apps. Closing your account follows the Account Terms. 4. After the end of your access, your duties under the Account Terms and Section 9 — in particular the deletion of Creator Data — continue. ## 12. Fees Access to the API is free of charge unless we agree otherwise with you in writing. Placement Fees, Commissions and other amounts remain governed by the Account Terms. ## 13. Client libraries and documentation 1. The client libraries and collections we publish are generated from the published contract. They are licensed under the MIT License, as stated in the package. 2. The code samples in the Docs are licensed under the MIT License as well; you may copy them into your integration. 3. The MIT License covers the code only. It grants no right to use the API, which these API Terms govern, and no right to the Creator Guard name or logo. ## 14. Warranties and liability 1. The API, the sandbox, the client libraries and the Docs are provided "as is" and "as available". To the maximum extent permitted by law, we give no warranty that they are uninterrupted, error-free or fit for a particular purpose. 2. Liability arising from or related to the API is part of, and does not add to, the liability cap of your Account Terms; no liability for indirect or consequential loss, including lost data or revenue caused by an outage, a throttled or refused request, a revoked Key or a retired major version. 3. **Indemnity.** You indemnify us — and any affected Creator — against claims arising from your integration, your OAuth app, the use of your Keys, or your breach of these API Terms. ## 15. Changes to these API Terms 1. **Versioned terms.** We publish each new version on the Platform, where `GET /v1/agreements` shows it, and announce it with the event `agreement.published` and in the changelog in the Docs. 2. **30 days' notice for adverse changes.** A material change that is adverse to you takes effect 30 days after we publish it. Other changes take effect on publication. 3. **Immediate changes.** A change that is legally required — by law, a court or an authority — or that is needed for the security of the API or to stop abuse takes effect on publication. 4. **Acceptance.** Your account accepts these API Terms once, by an owner or admin, in the portal or with `POST /v1/agreements/api_terms/accept`. Any accepted version counts, and continued use of the API after a new version takes effect constitutes acceptance — unless we mark a new version as "re-acceptance required"; then live writes need that version from the day it takes effect. 5. **The API contract is not changed through this Section.** Changes to the API itself (endpoints, fields, errors, limits) follow the versioning policy in the Docs (Section 8). ## 16. General Governing law: State of New Mexico; exclusive venue the state and federal courts in Bernalillo County, New Mexico. Notices: via the Platform or registered e-mail (to us: info@creator-guard.com), effective when sent; operational notices about Keys, limits and the API also through the API's events and the changelog. We may assign to a successor of the Platform; you may not assign without consent. No waiver by non-enforcement. Force majeure excuses delay, not amounts due. Sections 3(2), 5, 9, 11(4), 14 and this section survive termination. You consent to electronic contracting and records; the request log, the audit trail and other Platform logs are admissible business records. Headings are for convenience; "including" means "including without limitation"; the English version prevails over any translation. Severability applies — an unenforceable provision is replaced by the enforceable rule closest to its intent. --- # Data protection addendum for API partners (v1) Source: https://docs.creator-guard.com/legal/dpa/ **Effective:** upon publication · **Applies to:** every account that uses the Creator Guard API, from the acceptance by its owner or an admin, in addition to the terms you accepted for your account and the API Terms of Use. This addendum covers the personal data that you and Creator Guard exchange through the Creator Guard API. It applies in addition to the terms you accepted for your account (`GET /v1/agreements`). You and Creator Guard LLC are **independent controllers**: each of us decides why and how it uses the creator data it holds. You send us a creator so that we can introduce her to vetted management agencies, which is our own purpose. Neither of us processes data on behalf of the other. An owner or admin accepts this addendum once for your whole account, as its own agreement type: in the portal (Settings → API) or with `POST /v1/agreements/api_dpa/accept`. The acceptance is recorded with its time and, through the API, the key used. Your account needs it for live keys, live OAuth apps and live writes through the API; an account that already held a live key when this addendum was published may keep working without it for 30 days. Test keys work without it. ## 1. Parties - **Creator Guard:** Creator Guard LLC, a limited liability company organized under the laws of the State of New Mexico, United States of America, Business ID 0008125377, 1209 Mountain Road Pl NE #11622, Albuquerque, NM 87110, USA, info@creator-guard.com. - **Our representative in the EU** (Article 27 GDPR): MOXAMO GROUP Ltd, Palaion Patron Germanou 11, 8011 Paphos, Cyprus, info@moxamogroup.com. - **You:** the company or person that holds a Creator Guard partner or agency account and uses the API with it. ## 2. Subject and purpose Through the API you, as a referral partner, submit creators and keep their details up to date, upload their photos, send them consent and claim links, follow their progress and your commissions. As an agency you receive offers, accept or decline them, pay reservations, receive a creator's contact details after payment and report the outcome. Either kind of account can manage its team members, receive webhook events on its own servers and register OAuth apps through which a creator can connect her Creator Guard account to your dashboard. We use the data to review creators, introduce them to vetted management agencies, run your account and keep the API secure (rate limits, request log, audit events). ## 3. Roles - For the data you collect and keep in your own systems, you are the controller. - For the data we receive and process for our brokerage, Creator Guard LLC is the controller. - Neither of us processes data on behalf of the other under this addendum. - **Creator data you receive through an OAuth app** (her profile, status, consent state, her data-export file) is sent to you because she authorised your app on our consent screen. From then on you are the controller for that copy and process it under your own privacy policy, which your app must name. ## 4. Data and data subjects - **Creators you submit:** Name, Instagram handle, other contact details, platforms, follower count, niche and your notes; profile details such as age, gender, country, languages, content categories, availability and deal terms; photos; the status of her consent and age confirmation - **Creators who connect your OAuth app:** What she allowed with the app's scopes: profile, stage, matched agency (after payment), consent and 18+ status without IP address or browser, support messages, her data-export file - **Agencies' offers (agency accounts):** Before payment: the listing under her creator number (`CR-…`), photos she agreed to share as links valid for 1 hour. After payment: her name and contact details (`creator_name` is `null` until then) - **Your team:** Members and invitations (email address, role, who invited whom); account and key details (label, scopes, last use); the request log (route, status, time — no IP address, no request body); audit events (who changed keys, webhooks, members, the key policy or an authenticator, when, and from which IP address and client — in the portal and with an API key; kept 90 days). **Fraud check on consent records:** when a creator you submitted gives her consent or 18+ confirmation, we compare its IP address with the IP addresses your account's logins (owner and members) used within 30 days before or after — sessions and sign-ins, two-factor checks, audit events and terms acceptances, read where they are already kept, not copied. We store only the result (match yes / no, which kind of record and which login matched, when, same browser), never the IP addresses, for as long as her consent record exists. A match shows our admins a warning; nothing is blocked, no decision is taken on it alone, and you are not told **Special-category data.** A creator's age and content categories can reveal information about her sex life, which makes them special-category data under the GDPR (Article 9). With `consent_confirmed: true` you declare that she agreed to the referral and to you sending us these details. She confirms her consent and that she is 18 or older herself before any agency sees her profile. ## 5. Your obligations - Send a creator only with her agreement, and tell her that Creator Guard receives her details. - Send only what helps place her. Never put identity documents, passwords, payment details or explicit material into `notes`. - Keep API keys secret and revoke a leaked key at once. - Forward a creator's request for access or deletion that concerns our copy to info@creator-guard.com, with her creator number (`CR-…`). ## 6. Our obligations - Agencies see a creator's profile under her creator number, without her name or contact details, and only after she has confirmed her consent and her age. Only the agency that accepts her and pays the placement fee receives her name and contact details. - Her consent, her 18+ confirmation and her acceptance of the creator terms are given only on our own pages (consent link, creator portal), never through an app of the account that referred her (such a call answers `403 referrer_app_not_allowed`). She can withdraw her consent through any app she connected. - If she withdraws her consent, her listing goes offline for every agency that has not completed a placement with her, her deals that are not yet paid are cancelled, and every agency holding an offer for her receives the event `offer.consent_revoked`; it must then delete what it received about her within 30 days (Agency Terms). - We never tell you which agencies were involved, and we never tell another partner who submitted a creator first. - We answer data-subject requests for our copy and tell you when a request concerns data you sent. - What the API keeps about requests and integrations is deleted on fixed schedules ([Data retention](https://docs.creator-guard.com/data-retention/)). ## 7. Security measures - **Transport:** HTTPS only, TLS 1.2 or newer, HSTS. - **Keys:** stored only as SHA-256 hashes, with scopes per key and an optional IP allowlist and expiry; a revoked key stops working with the next request. - **OAuth:** authorization codes (60 seconds), access tokens (1 hour) and refresh tokens (30 days from last use) stored only as hashes; PKCE required; a creator can disconnect an app at any time. - **Passwords set on our pages** (join and claim links): checked against known breaches with the k-anonymity range API of Have I Been Pwned — only a 5-character hash prefix leaves our server. - **Members:** member changes in the portal need two-factor authentication; every change is in the audit trail. - **Least data:** each account sees only what its role allows; agencies never see who referred a creator; another account's resource answers `404`. - **Logs without creator data:** the request log holds the route template, status and timing, no creator data and no request bodies; events carry ids and are built from the current object at delivery time, except a few stored snapshots without creator contact data (a removed photo's metadata, the status of an export job or data request), kept 30 days. - **Photos:** re-encoded on upload; location and camera metadata are removed. - **Hosting:** our own server in France (OVHcloud, data centre in Gravelines) holds the database, logins and files; nightly encrypted backups on the same server, and OVHcloud keeps an encrypted copy of the server's files in Strasbourg, France, for 30 days. - **Administration:** admin access requires a two-factor login. ## 8. Sub-processors We use the providers listed under [Sub-processors](https://docs.creator-guard.com/legal/sub-processors/). We announce a new provider there and in the changelog, where reasonably possible before it receives API data. If you object, you may stop using the API. ## 9. Transfers outside the EU Creator Guard LLC is established in the USA; data you send from the EU is therefore transferred to the USA, although our database and servers are in France. The EU Standard Contractual Clauses (Commission Implementing Decision (EU) 2021/914, Module One, controller to controller) apply between you and us; they are incorporated into this addendum and concluded when you accept it. Creator data an agency outside the EU receives is covered by the Standard Contractual Clauses (Module One) in the Agency Terms. ## 10. Personal data breaches If a breach affects data the other party sent, each of us tells the other without undue delay, at the latest within 72 hours after becoming aware, and with what is known — to info@creator-guard.com for us, to your account's contact address for you. ## 11. Retention and deletion Leads stay while the creator is in the pipeline; she can ask for deletion at any time — by email, a support ticket or through an app she connected (`POST /v1/creator/deletion-request`). On deletion her consent records keep the decision, text version, channel and time, and lose the IP address and browser; these records are deleted 3 years after the placement ended or her data was deleted. What the API keeps about requests and integrations is deleted on fixed schedules ([Data retention](https://docs.creator-guard.com/data-retention/)): request log and audit events 90 days, idempotency keys 24 hours, events and webhook deliveries 30 days, OAuth codes and tokens 1 day after expiry, ended app connections 90 days, jobs 30 days, data-export files 7 days, unused claim links 30 days after expiry. Leads and listings have no fixed retention period: we keep them as long as necessary for the introduction and delete them on request. Team invitations are deleted 30 days after they were accepted, revoked or expired. ## 12. Term This addendum applies while you use the API and afterwards for as long as either of us still holds data received under it. ## 13. Governing law and venue This addendum is governed by the laws of the State of New Mexico, United States of America. Courts: the state and federal courts located in Bernalillo County, New Mexico. This does not limit a creator's rights under the GDPR or her right to complain to a supervisory authority. --- # Sub-processors Source: https://docs.creator-guard.com/legal/sub-processors/ Creator Guard LLC uses these providers to run the Creator Guard API. | Provider | What it does for the API | Where | Data it sees | |---|---|---|---| | OVHcloud (OVH Hosting Limited, Ireland) | Our own server in France: runs the database, logins and file storage for everything the API stores, the API, the platform with the OAuth authorization screen, the claim and join pages, these docs, the webhook delivery worker, the job that deletes expired data-export files and the nightly encrypted backups. OVHcloud also keeps an encrypted copy of the server's files for 30 days. | France (server in Gravelines, backup copy in Strasbourg) | All API data: accounts and their members and invitations, hashed keys, leads, listings, photos, offers and reservations, the consent ledger, OAuth apps, grants and hashed tokens, claim links, data-export files, request log, audit events, events; all API traffic (agency, partner and creator endpoints, OAuth), webhook deliveries to your servers and the backups | | Hostinger (Hostinger International Ltd.) | Our previous server in Frankfurt, used until 5 November 2026. It holds a stopped copy of the data until it is switched off. | Germany (Frankfurt) | The stopped copy and the backups made until 5 November 2026 | | Anthropic | AI extraction behind `POST /v1/extract`: the text you send is turned into profile fields; Creator Guard stores nothing from it. Anthropic does not use this text to train its models. | USA | The text sent to `POST /v1/extract` | | ALL-INKL.COM (Neue Medien Münnich, owner René Münnich) | E-mail: sends account e-mails such as confirmation codes, password resets, invitations and security notices, and hosts the mailbox of info@creator-guard.com (support and data-protection requests reach us there); also our domain name service. | Germany | Recipient e-mail address and message; emails you send us | ## Not sub-processors - **Error tracking** (GlitchTip) runs on our own server; no third party receives it. - **Backups** are encrypted and stored on our own server; OVHcloud's encrypted copy of the server's files is listed above. - **Agencies and referral partners** receive creator data under their own terms as independent recipients, not on our behalf — also when the agency API or webhooks deliver it to their own servers. - **Apps a creator connects** (OAuth) receive her data with her authorisation, for their operator's own purposes; their operator is an independent controller. - **Have I Been Pwned** (password check on our join, claim and password pages) receives only the first five characters of a SHA-1 hash of the new password (k-anonymity), no personal data. ## Changes to this list We add a provider to this page and announce it in the changelog, where reasonably possible before it receives API data. A partner who objects may stop using the API. --- # Data retention Source: https://docs.creator-guard.com/data-retention/ What the API keeps about requests and integrations is deleted automatically after a fixed time. The clean-up jobs run on a schedule — inside our database, and for export files a service on our own server; nothing waits for someone to remember it. | Data | Kept for | Deleted | |---|---|---| | API request log — `GET /v1/request-logs` shows you the last 30 days | 90 days | daily | | Idempotency keys and the stored first response | 24 hours | daily, once expired | | Audit events — `GET /v1/audit-events` | 90 days | daily | | Events — `GET /v1/events` | 30 days | daily | | Webhook deliveries and their attempts | 30 days | daily | | Data export files — the file behind a creator's data export link | 7 days | every few minutes, once the link expired | | Export jobs — `GET /v1/jobs/{id}` | 30 days | every 10 minutes, counted from when the job finished | | Unused claim links | 30 days | daily, counted from when the link expired | | Invitations to join an account — `GET /v1/members` | 30 days | daily, counted from when the invitation was accepted, revoked or expired | | OAuth authorization codes | 1 day | daily, counted from when the code expired | | OAuth access and refresh tokens | 1 day | daily, counted from when the token expired | | Revoked OAuth grants (a creator's connection to an app) with their codes and tokens | 90 days | daily, counted from the revocation | ## What these records hold - **Request log:** method, route template (`/v1/leads/{id}`, never the real URL), status, error code, request id, key and duration. No creator data, no request bodies, no IP address. - **Idempotency keys:** your key, a hash of the request and the first response, so that a retry gets the same answer. - **Audit events:** who created, rolled or revoked a key, changed a webhook endpoint, the key policy or an authenticator — with the time and, where we know it, the IP address and client. - **Data exports:** the file a creator asked for through an app (her profile, photos and records); 7 days after it is ready the export turns `expired` and the file is deleted. The record that she asked for an export stays. - **Export jobs:** the job's status and progress, never the exported data. - **Claim links:** a hash of the link, the lead it belongs to and when it expires. A used link stays as the record of who issued it. - **Invitations:** the invited email address, the role, who invited and a hash of the join link. The membership that an accepted invitation created stays as long as the person is a member. - **OAuth codes, tokens and grants:** hashes only, never a token itself; the grant records which app a creator connected and with which scopes. - **Events:** the event type, the ids it concerns and what changed (`previous_attributes`: the names of the changed fields, with the old value only for `stage` and `status`). Most payloads are built from the object's current state when the event is read or delivered, but a few events store a snapshot of their object with the event: a removed photo (`photo.removed`: its id, lead, kind, primary flag, consent status and timestamps — never the file or its storage path) and the job or data request a creator API event is about (`job.completed`, `data_export.ready`, `deletion_request.completed`: status and timestamps, no creator data). Snapshots are deleted with their event after 30 days. - **Webhook deliveries:** no payload is stored; for each delivery attempt the status code, duration and a short error. ## Leads and creator data Leads, listings, photos and confirmations are not on this list: they stay while the creator is in the pipeline. The same goes for the [consent ledger](https://docs.creator-guard.com/consent-ledger/), which is evidence: a decision made through an OAuth app keeps the app's name as it was at that moment, even if the app is renamed or deleted later. How a creator has her data removed is described under [Data protection](https://docs.creator-guard.com/data-protection/). ## Backups The database is backed up every night: encrypted copies on our own server, plus the daily backups of our database provider. Deleted data leaves the backups when they age out. --- # Service levels Source: https://docs.creator-guard.com/service-levels/ The API is in beta. These are the targets we run it against and measure continuously. They are not a contractual guarantee: there are no service credits. | What | Target | How we measure it | |---|---|---| | Availability of `/v1` | 99.5 % per calendar month (UTC) | A probe on our server calls `GET https://api.creator-guard.com/v1/` every minute, through DNS, TLS and the proxy like your requests. A minute counts as available when the answer is `200` within 5 seconds. The request log adds the share of all live requests answered without a server error (`5xx`). | | Single-resource reads | p95 under 500 ms | Server time of every `GET` on one resource, for example `GET /v1/leads/{id}`, from the request log: 95 % of these requests finish faster. | | Webhook delivery start | p95 under 60 s | Time from the event to the first delivery attempt, over all deliveries; manual replays are not counted. | ## What counts - **Live mode only.** Test-mode requests (keys `cg_test_…`) run against the sandbox and are not covered. - **Your errors are not our downtime.** Answers like `400`, `404` or `429` are the API working as documented; only server errors (`5xx`) and probe failures count against availability. - **Webhooks:** we measure when the first delivery attempt starts, not how fast your endpoint answers. Retries after a failed attempt follow the [webhook schedule](https://docs.creator-guard.com/webhooks/). ## Status page A public status page follows when the first partner contracts a service level. Until then, ask us about an incident at info@creator-guard.com.