ID Handling

Every payload in the NFL API is wired together by two identifier families. This page explains the families, how GUIDs address the feeds, how ids behave over time, and how NFL ids relate to other Sportradar products. The request mechanics live on NFL API Basics.

The Two ID Families

Every entity carries a GUID as its primary key, and most carry an sr_id URN alongside it:

A player profile shows both families in one payload, along with the references entries that link a player to his NCAA Football profile:

{
    "id": "3069db07-aa43-4503-ab11-2ae5c0002721",
    "name": "Josh Allen",
    "jersey": "17",
    "last_name": "Allen",
    "first_name": "Josh",
    "abbr_name": "J.Allen",
    "birth_date": "1996-05-21",
    "weight": 237.0,
    "height": 77,
    "position": "QB",
    "birth_place": "Firebaugh, CA, USA",
    "high_school": "Firebaugh (CA)",
    "college": "Wyoming",
    "college_conf": "Mountain West Conference",
    "rookie_year": 2018,
    "status": "ACT",
    "sr_id": "sr:player:1208608",
    "experience": 9,
    "salary": 36335281,
    "team": {
        "id": "768c92aa-75ff-4a43-bcc0-f2798c2e1724",
        "name": "Bills",
        "market": "Buffalo",
        "alias": "BUF",
        "sr_id": "sr:competitor:4376"
    },
    "draft": {
        "year": 2018,
        "round": 1,
        "number": 7,
        "team": {
            "id": "768c92aa-75ff-4a43-bcc0-f2798c2e1724",
            "name": "Bills",
            "market": "Buffalo",
            "alias": "BUF",
            "sr_id": "sr:competitor:4376"
        }
    },
    "references": [
        {
            "source_id": "00-0034857"
        },
        {
            "source_id": "46076"
        }
    ],
    "seasons": [
        {
            "id": "215f6286-3e05-476d-abe1-b2b0f5dfdff8",
            "year": 2018,
            "type": "PRE",
            "name": "PRE",
            "teams": [
                {
                    "id": "768c92aa-75ff-4a43-bcc0-f2798c2e1724",
                    "name": "Bills",
                    "market": "Buffalo",
                    "alias": "BUF",
                    "sr_id": "sr:competitor:4376"
                }
            ]
        }
    ]
}

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 type scope seasonal feeds. The list feeds provide the ids the rest of the API takes: the League Hierarchy and Teams feeds carry team ids, schedules carry game ids, and rosters carry player ids. The retrieval-path card on NFL API Basics walks the standard three-request path from a cold start.

URNs Bridge to Other Sportradar Products

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

Mapping API

The Mapping API provides on-demand, entity-level lookups that translate SR IDs (for example, sr:season:115087) into the Sportradar UUIDs used by the NFL API, 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.

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

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.

<team id="23ed0bf0-f058-11ee-9989-93cc4251593a" name="TBD" market="Team" alias="TBD"/>

Team Relocation

Team IDs will not change once created.

However, if a team relocates, a new team ID is created and tied to a franchise ID (franchise.id). For the Las Vegas Raiders (formerly Oakland), their Las Vegas team ID is 7d4fcc64-9cb5-4d1b-8e75-8a906d1e1576 and their Oakland team ID is 1c1cec48-6352-4556-b789-35304c1a6ae1, but both teams are linked to the 859f427c-5157-4b5a-90e4-066e83f46cc3 franchise ID.

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 an sr_id column for teams, players, games, and venues; it is the join key to other Sportradar products
• Keep franchise.id on teams if your model must survive relocations
• Ignore DUP-status profiles rather than deleting them, so re-pulls stay idempotent