External Keys

Most entities in the Betflow B2B API can be referenced by numeric ID or by a human-readable external key (slug). External keys are stable string identifiers that are easier to read and remember than numeric IDs.

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. Filter Parameters

Trends and betting endpoints accept key-based filter parameters alongside their ID equivalents:

{
  "sport_key": "basketball",
  "league_key": "nba",
  "player_key": "nikola-vucevic",
  "page": 1,
  "page_size": 10
}

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