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

# Resolve a messy team string to a Lumify team id

`POST /v1/resolve/team`

## Request

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

Resolve messy team names, abbreviations, metros, or aliases to a Lumify team_id using sport, league, event, or player clues. Returns ambiguous instead of guessing.

## Request body

- ResolveTeamRequest
  - `query` string: Team string: nickname, abbreviation, slug, metro, or alias (e.g. Niners, CIN, NY Giants).
  - `clues` ResolveTeamClues
    - `sport` string, nullable: Sport slug, e.g. nfl or mlb.
    - `league` string, nullable: League slug, tighter than sport (e.g. mls, epl).
    - `event_id` integer, nullable: Scope the match to this event's participants first.
    - `player_id` integer, nullable: Empty query uses this player's current team; otherwise a last-resort confirm.
    - `team_id` integer, nullable: Direct Lumify team id (also accepted as an all-digit query).
  - `options` ResolveTeamOptions
    - `max_candidates` integer: Maximum candidates to return when the match is ambiguous.
    - `min_confidence` number: Auto-resolve floor. Unique hits below this return ambiguous.

## Response `200`

resolved with team_id, or ambiguous / not_found. Never guesses when two catalog teams remain plausible.

- ResolveTeamResponse
  - `status` string, required: resolved | ambiguous | not_found | error
  - `team_id` integer, nullable: Set only when status is resolved.
  - `display_name` string, nullable: Catalog display name.
  - `sport` string, nullable: Resolved sport slug.
  - `league` string, nullable: Resolved league slug.
  - `abbreviation` string, nullable: Catalog abbreviation.
  - `confidence` number, nullable: Auto-resolve confidence.
  - `match_reasons` string[]: Why the unique bind matched.
  - `clues_used` string[]: Clue fields that were supplied.
  - `method` string, nullable: Kernel match method (abbreviation, nickname, alias, metro, …).
  - `sport_conflict` boolean: True when a ground-truth id/slug disagrees with an explicit sport or league clue.
  - `candidates` ResolveTeamCandidate[]: Plausible teams when status is ambiguous.
    - `team_id` integer, nullable: Lumify team id.
    - `display_name` string, nullable: Catalog display name.
    - `sport` string, nullable: Sport slug.
    - `league` string, nullable: League slug.
    - `abbreviation` string, nullable: Catalog abbreviation.
    - `confidence` number, nullable: Per-candidate confidence.
    - `match_reasons` string[]: Why this candidate matched.
  - `message` string, nullable: Human-readable status note.

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