---
title: "Resolve a messy player name to a Lumify player id"
method: POST
path: "/v1/resolve/player"
tags: ["resolve"]
---

# Resolve a messy player name to a Lumify player id

`POST /v1/resolve/player`

## Request

- Base URL: `https://lumify.ai`
- URL: `https://lumify.ai/v1/resolve/player`
- Auth: HTTP bearer

Resolve messy sports player names to a Lumify player_id using sport, team, or event clues. Prefer before grade_slip. Returns ambiguous instead of guessing.

## Request body

- ResolvePlayerRequest
  - `query` string: Messy player name or fragment, e.g. J. Chase.
  - `clues` ResolvePlayerClues
    - `sport` string, nullable: Sport slug, e.g. nfl or mlb.
    - `team_id` integer, nullable: Lumify team id.
    - `team_text` string, nullable: Team abbreviation, slug, or name (e.g. CIN).
    - `event_id` integer, nullable: Scope the match to this event's roster.
    - `position` string, nullable: Roster position abbreviation, e.g. WR or QB.
    - `vendor` string, nullable: Optional catalog source slug when vendor_player_key is set.
    - `vendor_player_key` string, nullable: Exact catalog key from a connected source, when you already have one.
    - `as_of` string, nullable: Reserved. Historical roster as-of is not applied in this version.
  - `options` ResolvePlayerOptions
    - `max_candidates` integer: Maximum candidates to return when the match is ambiguous.
    - `min_confidence` number: Auto-resolve floor. Unique hits below this return ambiguous.
    - `mode` string: strict (exact / Jr / F.Last on a roster), permissive (unique last-token on event/team roster), or ingest (sport-wide fuzzy).

## Response `200`

resolved with player_id, or ambiguous / not_found. Never guesses when two catalog players remain plausible.

- ResolvePlayerResponse
  - `status` string, required: resolved | ambiguous | not_found | error
  - `player_id` integer, nullable: Set only when status is resolved.
  - `display_name` string, nullable
  - `sport` string, nullable
  - `team_id` integer, nullable
  - `confidence` number, nullable
  - `match_reasons` string[]
  - `clues_used` string[]
  - `candidates` ResolvePlayerCandidate[]
    - `player_id` integer, nullable: Lumify player id.
    - `display_name` string, nullable: Catalog display name.
    - `sport` string, nullable
    - `team_id` integer, nullable
    - `confidence` number, nullable
    - `match_reasons` string[]
  - `message` string, nullable

## Other responses

- `422`: Validation Error

---

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