# 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.

curl:

```bash
curl -X POST https://api.creator-guard.com/v1/leads \
  -H "Authorization: Bearer $CG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_id": "crm-000042",
    "creator_name": "Mia",
    "instagram_handle": "@miacreates",
    "platforms": ["OnlyFans", "Instagram"],
    "consent_confirmed": true
  }'
```

JavaScript:

```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);
```

Python:

```python
# pip install requests
import os
import uuid
import requests

body = {
    "external_id": "crm-000042",
    "creator_name": "Mia",
    "instagram_handle": "@miacreates",
    "platforms": ["OnlyFans", "Instagram"],
    "consent_confirmed": True,
}

res = requests.request(
    "POST",
    "https://api.creator-guard.com/v1/leads",
    headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json=body,
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)
```

## 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/).
