ID Handling

Every payload in the NCAAFB API is wired together by GUID identifiers, with sr_id URNs riding on games. This page explains the id families, how GUIDs address the feeds, how ids behave over time, and how NCAAFB ids relate to other Sportradar products. The request mechanics live on NCAAFB API Basics.

The ID Families

Every entity carries a GUID as its primary key. Games also carry an sr_id URN; team and player rows do not:

THE ID FAMILIESGUIDs everywhere; URNs on games

GUID19775492-f1eb-4bc5-9e15-078ebd689c0f00f8bba0-4441-11f1-9c6d...the primary key on every entity

sr: URNsr:match:59838584games carry sr:match; team and player rows carry no URN

College rosters are GUID-only; NFL profiles link back to NCAAFB ids through their references entries.

A schedule entry shows the game-level pairing (trimmed to the game header):

{
    "week": {
        "games": [
            {
                "id": "fefcd061-2c97-4356-bf87-d11b398148fc",
                "status": "closed",
                "scheduled": "2025-09-05T23:00:00+00:00",
                "attendance": 48717,
                "entry_mode": "LDE",
                "coverage": "full",
                "sr_id": "sr:match:59838584",
                "game_type": "regular",
                "conference_game": false,
                "duration": "3:33",
                "expected_latency": 25,
                "home": {
                    "id": "1e8edb90-ea5e-4663-9a65-a30e51583711",
                    "name": "Louisville Cardinals",
                    "alias": "LOU",
                    "game_number": 2
                },
                "away": {
                    "id": "b59ad9ae-b8ec-4f8e-9bd2-ec5b4af41e57",
                    "name": "James Madison Dukes",
                    "alias": "JMU",
                    "game_number": 2
                }
            }
        ]
    }
}

GUIDs Address Every Feed

Request paths take GUIDs: team ids scope rosters and seasonal statistics, game ids scope the game feeds, player ids scope profiles, and season year plus REG scope seasonal feeds. The list feeds provide the ids the rest of the API takes: the League Hierarchy and Teams feeds carry team ids across all six divisions, schedules carry game ids, and rosters carry player ids. The retrieval-path card on NCAAFB API Basics walks the standard three-request path.

IDs in Other Sportradar Products

NCAAFB GUIDs stay within the NCAAFB API. Crossing products runs on game URNs or per-product reference fields:

Product	How the ids connect
NFL API	NCAAFB ids do not transfer; when a player reaches the NFL, his NFL profile's `references` entries carry his NCAAFB id
UFL API	NCAAFB player and venue ids are not synced to the UFL API; UFL player profiles link back to NCAAFB ids through their own `references` entries
Global American Football API	Runs on the `sr_id` system (`sr:competitor:...`, `sr:sport_event:...`); its mapping feeds translate ids in both directions
Odds APIs	Odds feeds run on `sr_id` URNs; each Odds API carries mapping feeds pairing `id` and `sr_id`
Images & Editorial	Asset and article entries carry both id forms under `entity_id`, so either key syncs content
NCAAFB Widgets	Widget inputs take the unique ids from the NCAAFB API feeds

Mapping API

The Mapping API provides on-demand, entity-level lookups that translate between Sportradar's two ID systems, SR IDs (for example, sr:season:134469) and Sportradar UUIDs, as well as select external provider ID systems. Rather than paginating through large mapping feeds, submit a supported SR ID and retrieve its mapping in a single targeted request.

Use it to link NCAA Football entities to the same competitions, teams, players, and events in other Sportradar products.

Each endpoint accepts an SR ID and returns mappings to Sportradar UUIDs by default.

Mapping Type	Endpoint	Input
Competition	Sport Competition Mappings	`sport_id`
Competitor	Season Competitor Mappings	`season_id`
Competitor	Sport Event Competitor Mappings	`sport_event_id`
Player	Season Player Mappings	`season_id`
Player	Sport Event Player Mappings	`sport_event_id`
Season	Competition Season Mappings	`competition_id`
Sport Event	Daily Sport Event Mappings	`sport_id` and `date`
Sport Event	Season Sport Event Mappings	`season_id`
Sport Event	Sport Event Mappings	`sport_event_id`

Season-level requests return a maximum of 100 records per page: paginate with the start or offset parameter. Cache mappings locally when your application repeatedly references the same entities.

For request samples, a full workflow, and the complete endpoint reference, see the Mapping API overview.

The TBD Placeholder Team

Within the Teams feed, you will find a TBD team. This unique ID can be used to populate game information when game matchups are not yet known. You can find more info on this process in the Playoffs integration scenario.

<home name="Team TBD" alias="TBD" id="e7ce7680-f058-11ee-89df-6558e107cb95">

Transferring Schools (Transfer Portal)

In NCAA Football, players can switch schools by entering the NCAA Transfer Portal, even mid-season. Mid-season transfers make the player ineligible to play until the next season, while off-season transfers help players avoid losing playing time and maintain academic progress.

You can track these moves directly using the NCAAFB Transfer Portal endpoint, which provides a list of all players currently in the NCAA Transfer Portal. A player’s ID remains constant even after transferring, ensuring you can track their career across teams without losing data continuity.

When IDs Change

A duplicate player profile (and player.id) can be introduced by mistake. In these cases, the duplicate is marked with a status of DUP. Profiles marked as duplicates can be ignored; they remain in the API rather than being removed, to avoid confusion.

The Daily Change Log surfaces the entities whose data changed each league day, so id-level corrections reach a synced store without full re-pulls; Monitoring Data Changes covers the workflow.

Choosing Storage Keys

Store GUIDs as primary keys. They are stable for the life of the entity and address every feed
Keep the game sr_id as the join key toward odds and other URN-based products
Expect no player or team URNs; cross-product player joins run through the NFL and UFL profiles' references entries
Ignore DUP-status profiles rather than deleting them, so re-pulls stay idempotent