---
title: "Resolve event identity from an id, player, or team clue"
method: POST
path: "/v1/resolve/event"
tags: ["resolve"]
---

# Resolve event identity from an id, player, or team clue

`POST /v1/resolve/event`

## Request

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

Resolve event_id, or player_id/team_id + date window, to a Lumify event_id. Never guesses.

## Request body

- ResolveEventRequest
  - `clues` ResolveEventClues
    - `event_id` integer, nullable: Direct Lumify event id (ground truth).
    - `player_id` integer, nullable: Find this player's event (falls back to roster team schedule).
    - `team_id` integer, nullable: Find this team's event. Add opponent_team_id for a matchup.
    - `opponent_team_id` integer, nullable: Narrows to a game against this team; requires team_id or player_id.
    - `start_date` string, nullable: Inclusive UTC YYYY-MM-DD. Requires end_date.
    - `end_date` string, nullable: Inclusive UTC YYYY-MM-DD. Requires start_date.
  - `options` ResolveEventOptions
    - `max_candidates` integer: Candidate cap when ambiguous.
    - `min_confidence` number: Auto-resolve floor.

## Response `200`

resolved with event_id, or ambiguous / not_found. Never guesses when two catalog events remain plausible in the window.

- ResolveEventResponse
  - `status` string, required: resolved | ambiguous | not_found | error
  - `event_id` integer, nullable: Set only when status is resolved.
  - `sport` string, nullable
  - `league` string, nullable
  - `event_status` string, nullable: scheduled | final | …
  - `starts_at` string, nullable: ISO 8601 kickoff.
  - `home_team` string, nullable
  - `away_team` string, nullable
  - `confidence` number, nullable
  - `match_reasons` string[]
  - `clues_used` string[]
  - `method` string, nullable: event_id | player_window | player_team_window | team_window | matchup_window.
  - `participant_conflict` boolean: True when event_id conflicts with an explicit player/team clue or date window.
  - `candidates` ResolveEventCandidate[]: Plausible events when ambiguous.
    - `event_id` integer, nullable
    - `sport` string, nullable
    - `league` string, nullable
    - `event_status` string, nullable: scheduled | final | …
    - `starts_at` string, nullable: ISO 8601 kickoff.
    - `home_team` string, nullable
    - `away_team` string, 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)