Resolve a creator by NAME (no handle) → ranked candidates

Identity-first name resolution. Give a free-text creator name and get back ranked CANDIDATE creators: first from our own index (each with an identity_group_id, whether they're already_scored, and their cross-platform accounts), and — only when nothing is indexed — a single Google-Search-verified candidate footprint (source='web_search'). Nothing is auto-attributed: every candidate carries a match_confidence (0-1) and a source, so confirm the right person before scoring. The index lookup is FREE (0 credits) and performs NO scrape. The web-search fallback is OPT-IN via allow_web_search (default false) and is billed at the discovery rate, because it runs the same web-grounded lookup as /creators/discover; it requires a full-scope key. After picking a candidate, score it with POST /creators/vet (indexed accounts) or POST /creators/discover (complete a footprint from a handle).

post/creators/resolve

Request

  • Base URL: https://creatorscore.io/api/v1
  • URL: https://creatorscore.io/api/v1/creators/resolve
  • Auth: API key in header X-API-Key

Headers

X-Customer-Refstring

Your own end-customer identifier for this read (a credit licenses ONE end-customer's evaluation of ONE creator). Logged with the request so per-brand usage is reconcilable on both sides. Opaque to us.

Request body

namestring

Free-text creator name to resolve. Use this OR handle.

handlestring

A known @handle (without @) — exact, case-insensitive index match; never web-searches. Use this OR name.

platformstring

Optional platform to scope a handle lookup when the same handle exists on several platforms.

min_confidencenumber

Drop web-search-discovered accounts below this confidence (only affects the web fallback).

allow_web_searchboolean

Opt in to the paid web fallback when the index has no strong match. Billed at the discovery rate; requires a full-scope key. Left false, resolution is index-only and free.

Response

query + candidates[] (each with identity_group_id|null, display_name, match_confidence, source, already_scored, last_scored_at, score_age_days, is_stale, total_followers, accounts[]) + ambiguous + resolution_method ('index'|'web_search'|'mixed'|'none') + credits_charged (0 unless the opt-in web fallback ran) + web_search_used + web_search_skipped_reason (null, 'read_only_key', 'insufficient_credits', or 'daily_discovery_budget_exhausted' — so an empty result is never mistaken for 'this creator does not exist'). is_stale=true means the score is over 30 days old (or never scored) — rescore before relying on it.

object required

Changes

No recorded changes to this operation across all 1 revision of this API.