External Keys

Most entities in the Odditt B2B API can be referenced by numeric ID or by a human-readable external key (slug).

📘
Numeric IDs are the canonical identifiers - use them in production.
External keys are a convenience for manual exploration, quick demos, and readable examples. They are not recommended as the identifier you build an integration on: keys can be shared by multiple entities (a bare ambiguous key returns 400), and ID lookups are always exact. Resolve entities to their numeric IDs once via the reference endpoints and key everything on IDs from there.

Format

External keys use lowercase letters, digits, and hyphens. Dots (.) act as hierarchy separators when disambiguation is needed.

Pattern: lowercase-slug or parent.child-slug

Keys are case-insensitive - NBA, nba, and Nba all resolve to the same league.

Key Types

Sports

Single-level only.

Format	Example
`{sport_key}`	`american-football`

curl https://api.odditt.com/v1/references/sports/american-football \
 -H "X-API-Key: YOUR_API_KEY"

Leagues

Optional country prefix for disambiguation.

Format	Example
`{league_key}`	`nba`
`{country_key}.{league_key}`	`united-states.nba`

curl https://api.odditt.com/v1/references/leagues/nba \
 -H "X-API-Key: YOUR_API_KEY"

Teams

Optional league prefix for disambiguation.

Format	Example
`{team_key}`	`new-england-patriots`
`{league_key}.{team_key}`	`nfl.new-england-patriots`

Players

Up to three levels of hierarchy.

Format	Example
`{player_key}`	`nikola-vucevic`
`{team_key}.{player_key}`	`boston-celtics.nikola-vucevic`
`{league_key}.{team_key}.{player_key}`	`nba.boston-celtics.nikola-vucevic`

Use longer forms when a shorter key matches multiple entities (e.g. a player name shared across leagues).

Operators

Single-level only.

Format	Example
`{operator_key}`	`draftkings`

Countries

Single-level only.

Format	Example
`{country_key}`	`italy`

Using External Keys

External keys work in two contexts:

1. Path Parameters

Reference endpoints accept either an ID or a key in the URL path:

# By ID
curl https://api.odditt.com/v1/references/teams/42 \
 -H "X-API-Key: YOUR_API_KEY"

# By external key
curl https://api.odditt.com/v1/references/teams/nfl.new-england-patriots \
 -H "X-API-Key: YOUR_API_KEY"

2. Sport Filter

Flow endpoints accept sport_key as an alternative to sport_id:

{
  "sport_key": "basketball",
  "page": 1,
  "page_size": 10
}

All other flow filtering is by numeric ID (league_ids, team_ids, player_ids, ...) - resolve entities to IDs via the reference endpoints first.

ID vs Key Precedence

When both an ID and a key are provided for the same entity, the ID always takes precedence and the key is ignored:

{
  "sport_id": 1,
  "sport_key": "basketball"
}

In this example, sport_id: 1 is used and sport_key is ignored.

Ambiguous Keys

If a short key matches multiple entities, the API returns a 400 Bad Request error. Use a longer, qualified form to disambiguate:

# Ambiguous - might match players in multiple leagues
curl https://api.odditt.com/v1/references/players/tre-jones

# Disambiguated - specify the team
curl https://api.odditt.com/v1/references/players/chicago-bulls.tre-jones