ID Handling

Every entity in the UFL API (game, team, player, venue, tournament, season, week) is keyed by a GUID, and several entity types also carry a Sportradar URN in an sr_id field. This page covers what each family is for, which IDs to store, and the situations where an ID you hold stops being the right one.

The Two ID Families

GUIDs Are the Primary Keys

The id field on every entity is a GUID, and it is the value every path parameter expects: /games/{game_id}/boxscore, /teams/{team_id}/full_roster, /players/{player_id}/profile, /tournaments/{tournament_id}/summary. The same GUID addresses the same entity in every feed, so schedule rows, boxscores, rosters, and statistics all join on it directly.

A schedule entry shows the pattern: the game, the venue, and both teams each carry their GUID, and the game, venue, and teams also carry URNs:

{
  "id": "475db4da-d8a9-49ee-b7a4-1239f916533a",
  "status": "closed",
  "scheduled": "2026-06-13T19:00:00+00:00",
  "sr_id": "sr:match:71976470",
  "game_type": "playoff",
  "title": "United Bowl",
  "venue": {
    "id": "59e88b40-c046-11ee-9772-5f005754c5a2",
    "name": "Audi Field",
    "city": "Washington",
    "state": "DC",
    "sr_id": "sr:venue:27207"
  },
  "home": {
    "id": "ff1f47e0-b8ef-11f0-9440-2f32b8d49d12",
    "name": "Louisville Kings",
    "alias": "LOU",
    "sr_id": "sr:competitor:1320808",
    "game_number": 2
  },
  "away": {
    "id": "a3407150-c045-11ee-b66f-5d382d09dbaf",
    "name": "DC Defenders",
    "alias": "DC",
    "sr_id": "sr:competitor:661851",
    "game_number": 2
  }
}

URNs Bridge to Other Sportradar Products

The sr_id values (sr:match:, sr:competitor:, sr:venue:) identify the same game, team, or venue in URN-keyed Sportradar products, such as the Odds Comparison APIs. Store them as attributes alongside the GUID rather than as keys. Player rows carry no sr_id; players are addressed by GUID only:

{
  "id": "1fb50210-f00e-11f0-843c-4f6a1fca4997",
  "name": "Chandler Rogers",
  "jersey": "04",
  "last_name": "Rogers",
  "first_name": "Chandler",
  "abbr_name": "C.Rogers",
  "birth_date": "2001-10-23",
  "weight": 197.0,
  "height": 72,
  "position": "QB",
  "age": 24,
  "birth_place": "Mansfield, TX, USA",
  "high_school": "Lake Ridge (TX)",
  "college": "California",
  "college_conf": "Atlantic Coast Conference",
  "status": "started",
  "in_game_status": "active"
}

One cross-product link does exist for players: when a player also has a record in the NCAA Football API, the Player Profile's references array carries that link (an id_type of league_profile scoped to NCAAFB). The entry is created when the player is added; players without an NCAA Football record carry no references entry.

The TBD Placeholder Team

The Teams feed includes a placeholder team named TBD used for matchups whose participants are not yet decided, such as postseason slots before seeding settles. It has its own stable GUID and no URN. Filter it out of team pickers and standings displays, and treat a schedule entry pointing at it as "participant to be determined":

{
  "league": {
    "id": "d441365f-cfab-49d6-9976-6c95d91fdef7",
    "name": "United Football League",
    "alias": "UFL"
  },
  "teams": [
    {
      "id": "ff1f47e0-b8ef-11f0-9440-2f32b8d49d12",
      "name": "Kings",
      "market": "Louisville",
      "alias": "LOU",
      "sr_id": "sr:competitor:1320808"
    },
    {
      "id": "11e96200-f058-11ee-ab1b-3fb8baf42b4f",
      "name": "TBD",
      "market": "Team",
      "alias": "TBD"
    }
  ]
}

When IDs Change

• Postponed games: a postponed game's makeup arrives as a new game ID on the announced date; the original entry keeps the postponed status. Re-pull the schedule feeds to pick up makeup games.
• Deleted games: the Weekly and Season Schedules carry a deleted_games array of IDs that no longer belong to the schedule, the Daily Change Log lists the day's removals, and a removed game's own feeds flag it with deleted: true; drop the listed IDs from your store. The Monitoring Data Changes page covers the reconciliation loop.
• Suspended games: a suspended game resumes later under the same game ID; keep polling it.
• Franchise identity: team GUIDs are stable, but market, name, and alias can change between seasons as franchises move or rebrand. The Team Roster feed's franchise object carries the underlying franchise name; key on the GUID and refresh display fields from the Teams feed each season.

Choosing Storage Keys

• Key games, teams, players, venues, and tournaments by GUID
• Store sr_id URNs as attributes on games, teams, and venues for cross-product joins
• Store season id values from Seasons; the {season_year}/{season_type} pair addresses the same season in path parameters
• Treat names, aliases, markets, and jersey numbers as display data, never as keys