Canonical IDs

uniqueTournament.id vs tournament.id — which to store, which to query, and how to avoid season-rollover breakage

The dual-ID model

Every Football V2 competition is identified by two numeric IDs that look interchangeable but are not. uniqueTournament.id is the canonical, season-independent identifier for a league or competition. tournament.id is a per-season, per-group variant that changes every year and is only meaningful when paired with a seasonId.

Mixing them up is the single most common cause of broken integrations — IDs that worked last season silently stop resolving when the new season rolls over.

---

Side-by-side

Field	Scope	Stable across seasons?	Use for
uniqueTournament.id	League / competition (e.g. “Premier League”)	✅ Yes — never changes	Storage, filtering, image lookup, cross-season queries
tournament.id	A specific season + group within a competition	❌ No — regenerated yearly	Only as a parameter to season-scoped endpoints (standings, top scorers, brackets)

Worked example

A trimmed /api/event/{id} response shows both fields side by side:

{
  "event": {
    "id": 12436891,
    "tournament": {
      "id": 1,
      "name": "Premier League 25/26",
      "uniqueTournament": {
        "id": 17,
        "name": "Premier League",
        "category": { "id": 1, "name": "England", "alpha2": "EN" }
      }
    },
    "season": { "id": 76986, "name": "Premier League 25/26", "year": "25/26" }
  }
}

• tournament.uniqueTournament.id = 17 → store this. It will still be 17 in 2030.
• tournament.id = 1 → never store this. Next season it’s a different number.
• season.id = 76986 → discover dynamically via /api/tournaments/17/seasons whenever you need season-scoped data.

---

Confirmed canonical IDs (top competitions)

Competition	uniqueTournament.id
Premier League	17
LaLiga	8
Bundesliga	35
Serie A	23
Ligue 1	34
UEFA Champions League	7
UEFA Europa League	679
FA Cup	19
MLS	242
FIFA World Cup	16

If you’ve seen a different ID for one of these in the wild (e.g. 49 for FA Cup, 1 for Premier League, 104 for MLS), you were looking at the per-season tournament.id, not the canonical one.

---

When to use which

Use uniqueTournament.id when:

• Storing a competition reference in your database
• Filtering matches, fixtures, or teams by competition
• Loading a league logo via /images/tournaments/{id}
• Querying competition-level metadata that doesn’t depend on the current season

Use tournament.id (paired with seasonId) only when:

• Calling season-scoped endpoints such as:
  • /api/tournament/{tournamentId}/season/{seasonId}/standings
  • /api/tournament/{tournamentId}/season/{seasonId}/top-players/...
  • /api/tournament/{tournamentId}/season/{seasonId}/cuptrees

And in those cases, resolve tournament.id and seasonId dynamically every time — don’t cache them past a single season.

Resolution flow

Have:    uniqueTournament.id (e.g. 17 for Premier League)
   │
   ▼
GET /api/tournaments/17/seasons   ← discover current seasonId
   │
   ▼
seasonId (e.g. 76986)
   │
   ▼
GET /api/tournament/{tournamentId}/season/{seasonId}/standings

The tournamentId for the season-scoped call comes from the same seasons response — never hardcode it.

---

Anti-pattern

Never persist tournament.id as a foreign key. It will silently break at the next season rollover when SportsAPI Pro regenerates per-season IDs. Every integration that hits us with “the league suddenly stopped working in August” has done exactly this.

Related

• Tournament endpoints reference
• Search endpoint — discover uniqueTournament.id by name
• One-Time ID Migration Guide
• Image endpoint troubleshooting