---
title: "Resolve a creator by NAME (no handle) → ranked candidates"
method: POST
path: "/creators/resolve"
---

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

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

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

## Headers

- `X-Customer-Ref` string

## Request body

- object: Provide either 'name' or 'handle'.
  - `name` string: Free-text creator name to resolve. Use this OR handle.
  - `handle` string: A known @handle (without @) — exact, case-insensitive index match; never web-searches. Use this OR name.
  - `platform` string: Optional platform to scope a handle lookup when the same handle exists on several platforms.
  - `min_confidence` number: Drop web-search-discovered accounts below this confidence (only affects the web fallback).
  - `allow_web_search` boolean: 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 `200`

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

## Other responses

- `400`: Invalid request body.
- `401`: Missing or invalid API key.
- `429`: Per-key rate limit hit (120 req/min). Retry after the duration in the Retry-After header.
- `503`: Creator index lookup failed.

---

[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)