---
title: "Start a Social Background Check (Quick or Verified, $29.99, paid via Stripe — not credits)"
method: POST
path: "/background-checks"
---

# Start a Social Background Check (Quick or Verified, $29.99, paid via Stripe — not credits)

`POST /background-checks`

## Request

- Base URL: `https://creatorscore.io/api/v1`
- URL: `https://creatorscore.io/api/v1/background-checks`
- Auth: API key in header `X-API-Key`

Starts a Social Background Check: a one-shot, full-history brand-safety scan producing a categorized report of findings (hate/NSFW/violence/profanity/political/legal and more), each with evidence. NO SCORE IS PRODUCED — a Background Check is a distinct product from the CreatorScore. Billing is a one-time Stripe payment, NOT API credits: the response returns a payment_url the brand completes in the browser. Tiers: QUICK ($29.99 / €27.99, default) scans public history and starts automatically when payment clears. VERIFIED ($29.99 / €27.99, tier:'verified') adds creator-authorized content (OAuth-pulled posts, dense video frames, transcripts, deleted-content recovery) and requires creator_email: after payment the creator is emailed a consent link, the check waits in status 'awaiting_consent' until they authorize, then the scan runs; it is auto-refunded if they never do. Full-scope key required.

## Request body

- object
  - `handle` string, required
  - `platforms` string[], required: Platforms to scan.
  - `creator_name` string
  - `currency` 'usd' | 'eur'
  - `tier` 'quick' | 'verified': verified requires creator_email; the creator must consent before the scan runs.
  - `creator_email` string, email: Verified tier only: where the consent link is sent.
  - `consent_reasons` string: Verified tier only: shown to the creator in the consent request.
  - `provided_handles` object: Optional per-platform handles for platforms fetched by handle rather than OAuth (e.g. twitter).
  - `buyer` object: Who the check is for. Public-record reports (public figures) end with a brand-fit verdict written for this brand and category; omitted → the workspace default.
    - `brand_name` string
    - `category` string: alcohol | beverage | food | beauty | fashion | sportswear | luxury | gaming | tech | telecom | finance | crypto | gambling | automotive | travel | health | wellness | family | education | entertainment | home | b2b | public | other
    - `notes` string: Campaign context: product, markets, audience, sensitivities.

## Response `200`

check_id + status='awaiting_payment' + tier + amount (cents) + currency + payment_url + platforms (+ creator_email for verified). After payment: quick → 'processing' → 'completed'; verified → 'awaiting_consent' → 'processing' → 'completed' (or refunded if the creator never authorizes). Poll GET /background-checks/{id}.

- object

## Other responses

- `400`: Invalid request, or creator_email_required for tier:'verified'.
- `401`: Missing or invalid API key.
- `403`: Read-only API key attempted to queue a fresh score (cache miss). Cached lookups and job-status reads are allowed on read-only keys; queueing requires a full-scope key. error='insufficient_scope'.
- `429`: Per-key rate limit hit (120 req/min). Retry after the duration in the Retry-After header.
- `502`: payment_setup_failed — Stripe checkout couldn't be created. Retry.

---

[API](https://skmtc.dev/creatorscore/apis/creatorscore-api.md) · [All operations](https://skmtc.dev/creatorscore/apis/creatorscore-api/llms.txt) · [OpenAPI document](https://skmtc.dev/creatorscore/apis/creatorscore-api/revisions/d3a219842277?raw)