Rosters
This guide helps you access comprehensive information on NFL transactions, rosters, and injuries. You'll learn how to effectively query endpoints for real-time transaction updates, specific game rosters, in-game injuries, and player participation, along with how to distinguish between full rosters and team profiles, and how to keep track of weekly injuries and depth charts.
Introduction to Rosters
An NFL roster is essentially the lineup of players registered under a team. You can access rosters using three feeds:
- The Team Roster endpoint provides the complete roster of players, including those on the practice squad.
- The Team Profile endpoint provides a roster of the active players.
- Lastly, each team must declare their game roster before each game, specifying which players from the full roster will be active. This information is available through the Game Roster endpoint.
What is a practice squad?
The practice squad is a group of players who practice with the team but are not eligible to play in official games unless promoted to the active roster. This allows teams to develop players and have them readily available should they need replacements due to injury or other reasons during the season.
Prerequisite - Accessing Available Seasons
To avoid confusion and ensure you're accessing available data, refer to our Seasons feed. This resource lists all the seasons for which we have data.
For example: To ensure data availability for future seasons, such as a schedule in advance of when a season begins, first check the Seasons feed to verify that data for that specific season is already provided.
Starting with this feed can prevent unnecessary errors and streamline your data retrieval process.
How to Get Rosters
Accessing Team Rosters
- Get a team ID: You can access a list of all active teams in the NFL API database with the Teams endpoint.
- Call the Team Roster or Team Profile endpoints: For the entire roster, use the Team Roster endpoint. To see active players only, use the Team Profile endpoint.
Recommended Pull Frequency:
- Updates are made in real-time as changes are made to rosters or player profiles.
- Pull every hour or less depending on your use case.
- The TTL/Cache is 300 seconds.
Tip - Utilize Team Franchise Data
You can also use the Team Roster and Team Profile endpoints to access detailed franchise data for NFL teams. This information includes the team's founding year, current owner, nicknames, records of championships and division titles won and more.
Example - Team Roster:
{
"id": "768c92aa-75ff-4a43-bcc0-f2798c2e1724",
"name": "Bills",
"market": "Buffalo",
"alias": "BUF",
"sr_id": "sr:competitor:4376",
"founded": 1960,
"owner": "Terry and Kim Pegula",
"general_manager": "Brandon Beane",
"president": "Kim Pegula",
"mascot": "Billy Buffalo",
"fight_song": "Shout",
"championships_won": 0,
"conference_titles": 4,
"division_titles": 11,
"playoff_appearances": 19,
"franchise": {
"id": "26f22bc6-1fb9-4c01-80cc-908342490651",
"name": "Bills",
"alias": "BUF"
},
"venue": {
"id": "e9e0828e-37fc-4238-a317-49037577dd55",
"name": "Highmark Stadium",
"city": "Orchard Park",
"state": "NY",
"country": "USA",
"zip": "14127",
"address": "One Bills Drive",
"capacity": 71608,
"surface": "artificial",
"roof_type": "outdoor",
"sr_id": "sr:venue:8171",
"location": {
"lat": "42.773826",
"lng": "-78.786589"
}
},
"division": {
"id": "b95cd27d-d631-4fe1-bc05-0ae47fc0b14b",
"name": "AFC East",
"alias": "AFC_EAST"
},
"conference": {
"id": "1bdefe12-6cb2-4d6a-b208-b04602ae79c3",
"name": "AFC",
"alias": "AFC"
},
"coaches": [
{
"id": "0f0a2a50-bf99-11ee-b910-d944903b5e58",
"full_name": "Bobby Babich",
"first_name": "Bobby",
"last_name": "Babich",
"position": "Defensive Coordinator"
},
{
"id": "24ddc0fb-4e6f-4c67-b3c1-8fa7acd691cc",
"full_name": "Sean McDermott",
"first_name": "Sean",
"last_name": "McDermott",
"position": "Head Coach"
},
{
"id": "2546eccb-38e4-486d-9c69-c7d5215eaf34",
"full_name": "Joe Brady",
"first_name": "Joe",
"last_name": "Brady",
"position": "Offensive Coordinator"
}
],
"players": [
{
"id": "007971f0-f012-11ed-833c-ebfbb713adc7",
"name": "Richard Gouraige",
"jersey": "75",
"last_name": "Gouraige",
"first_name": "Richard",
"abbr_name": "R.Gouraige",
"birth_date": "1998-10-15",
"weight": 306,
"height": 77,
"position": "T",
"birth_place": "Tampa, FL, USA",
"high_school": "Cambridge Christian School (FL)",
"college": "Florida",
"college_conf": "Southeastern Conference",
"rookie_year": 2023,
"status": "ACT",
"sr_id": "sr:player:1413309",
"experience": 1
},
{
"id": "014038bd-e9b7-476f-b7bd-bd78a46a9a57",
"name": "Austin Johnson",
"jersey": "98",
"last_name": "Johnson",
"first_name": "Austin",
"abbr_name": "A.Johnson",
"birth_date": "1994-05-08",
"weight": 314,
"height": 76,
"position": "DT",
"birth_place": "Galloway, NJ, USA",
"high_school": "St. Augustine Prep (NJ)",
"college": "Penn State",
"college_conf": "Big Ten Conference",
"rookie_year": 2016,
"status": "ACT",
"sr_id": "sr:player:987663",
"experience": 8,
"draft": {
"year": 2016,
"round": 2,
"number": 43,
"team": {
"id": "d26a1ca5-722d-4274-8f97-c92e49c96315",
"name": "Titans",
"market": "Tennessee",
"alias": "TEN",
"sr_id": "sr:competitor:367364"
}
}
},
Use Cases:
- Team Roster: By integrating this data, you can offer your users comprehensive information about the Buffalo Bills, including team history, current ownership, and key staff like the head coach and coordinators. Additionally, you can display stats for specific players, details about the home venue, and historical performance metrics like playoff appearances and division titles.
- Team Profile: If you are developing a mobile app for fantasy football enthusiasts, you might want to display only the active players on NFL teams. This feature allows users to make informed decisions for their fantasy drafts and team management by providing up-to-date information on which players are currently active and eligible to score points in upcoming games.
The following is an example of how you can display a team roster on your platform, showcasing key details such as player names, jersey numbers, positions, age, height, weight, college, and birthplace.
Accessing Headshots and Team Logos
To access team logos and player headshots, use the Images API.
Accessing Game Rosters
- Get a game ID: You can access a list of upcoming games using any one of the following endpoints:
- Call the Game Roster Endpoint: Use your game ID to call the Game Roster endpoint.
Recommended Pull Frequency:
- This endpoint will update every two seconds once a game status changes to inprogress. After the game concludes, update frequency will adjust to every 120 seconds.
- For Live Updates: Begin pulling game feeds around 90 minutes prior to the scheduled start; this is when NFL teams announce inactive players for their game. At this time, affected players are adjusted to
deactivated. Then, at the conclusion of the game, players are adjusted tostartedandplayedas necessary. Continue to request data every two seconds to match the Time to Live (TTL) when the game is live to receive in-game player status updates. - For Non-Live Updates: Retrieve data on an as-needed basis, ensuring not to pull data until 10 minutes before the game starts, even if the game is not live.
Example - Game Roster:
{
"id": "110704e9-21f9-4ef8-ab83-df09573c1a9f",
"status": "inprogress",
"scheduled": "2023-09-12T00:15:00+00:00",
"attendance": 83345,
"entry_mode": "LDE",
"clock": "9:02",
"quarter": 5,
"sr_id": "sr:match:41205261",
"game_type": "regular",
"conference_game": true,
"title": "Monday Night Football",
"duration": "2:58",
"weather": {
"condition": "Rain",
"humidity": 88,
"temp": 72,
"wind": {
"speed": 3,
"direction": "N"
}
},
"summary": {
"season": {
"id": "a538d200-e916-4272-aa07-b486094a1668",
"year": 2023,
"type": "REG",
"name": "REG"
},
"week": {
"id": "b97007d7-03b1-4ef9-8fb1-d96d7abdb722",
"sequence": 1,
"title": "1"
},
"venue": {
"id": "5d4c85c7-d84e-4e10-bd6a-8a15ebecca5c",
"name": "MetLife Stadium",
"city": "East Rutherford",
"state": "NJ",
"country": "USA",
"zip": "07073",
"address": "One MetLife Stadium Drive",
"capacity": 82500,
"surface": "artificial",
"roof_type": "outdoor",
"sr_id": "sr:venue:1981",
"location": {
"lat": "40.813611",
"lng": "-74.074444"
}
},
"home": {
"id": "5fee86ae-74ab-4bdd-8416-42a9dd9964f3",
"name": "Jets",
"market": "New York",
"alias": "NYJ",
"sr_id": "sr:competitor:4427",
"used_timeouts": 0,
"remaining_timeouts": 2,
"points": 22,
"used_challenges": 0,
"remaining_challenges": 2,
"record": {
"wins": 7,
"losses": 10,
"ties": 0
}
},
"away": {
"id": "768c92aa-75ff-4a43-bcc0-f2798c2e1724",
"name": "Bills",
"market": "Buffalo",
"alias": "BUF",
"sr_id": "sr:competitor:4376",
"used_timeouts": 0,
"remaining_timeouts": 2,
"points": 16,
"used_challenges": 0,
"remaining_challenges": 2,
"record": {
"wins": 11,
"losses": 6,
"ties": 0
}
}
},
"home": {
"id": "5fee86ae-74ab-4bdd-8416-42a9dd9964f3",
"name": "Jets",
"market": "New York",
"alias": "NYJ",
"sr_id": "sr:competitor:4427",
"coaches": [
{
"id": "dbb6b084-bcea-4e58-986d-225a93527333",
"full_name": "Jeff Ulbrich",
"first_name": "Jeff",
"last_name": "Ulbrich",
"position": "Defensive Coordinator"
},
{
"id": "51ba5ef6-cab8-4815-9333-06f598746486",
"full_name": "Nathaniel Hackett",
"first_name": "Nathaniel",
"last_name": "Hackett",
"position": "Offensive Coordinator"
},
{
"id": "7ff285b3-e38c-4ba8-92c2-b46fd35e5c01",
"full_name": "Robert Saleh",
"first_name": "Robert",
"last_name": "Saleh",
"position": "Head Coach"
}
],
"players": [
{
"id": "179de740-ebac-11ed-93d2-d3fce4d12388",
"name": "Caleb Johnson",
"jersey": "43",
"last_name": "Johnson",
"first_name": "Caleb",
"abbr_name": "C.Johnson",
"birth_date": "1998-07-14",
"weight": 235,
"height": 73,
"position": "LB",
"age": 25,
"birth_place": "Murrieta, CA, USA",
"high_school": "Vista Murrieta (CA)",
"college": "Miami (FL)",
"college_conf": "Atlantic Coast Conference",
"rookie_year": 2023,
"status": "dnp",
"sr_id": "sr:player:2006529",
"in_game_status": "active"
},
{
"id": "6a23db75-021b-4808-99e6-21a33d34202b",
"name": "Allen Lazard",
"jersey": "10",
"last_name": "Lazard",
"first_name": "Allen",
"abbr_name": "A.Lazard",
"birth_date": "1995-12-11",
"weight": 227,
"height": 77,
"position": "WR",
"age": 27,
"birth_place": "Urbandale, IA, USA",
"high_school": "Urbandale (IA)",
"college": "Iowa State",
"college_conf": "Big Twelve Conference",
"rookie_year": 2018,
"status": "started",
"sr_id": "sr:player:1229760",
"in_game_status": "active"
},
{
"id": "440bf3a1-d373-4f11-b702-26fb8f62c035",
"name": "Marquiss Spencer",
"jersey": "51",
"last_name": "Spencer",
"first_name": "Marquiss",
"abbr_name": "M.Spencer",
"birth_date": "1997-07-16",
"weight": 295,
"height": 76,
"position": "DL",
"age": 26,
"birth_place": "Greenwood, MS, USA",
"high_school": "Greenwood (MS)",
"college": "Mississippi State",
"college_conf": "Southeastern Conference",
"rookie_year": 2021,
"status": "dnp",
"sr_id": "sr:player:2198130",
"in_game_status": "active",
"draft": {
"year": 2021,
"round": 7,
"number": 253,
"team": {
"id": "ce92bd47-93d5-4fe9-ada4-0fc681e6caa0",
"name": "Broncos",
"market": "Denver",
"alias": "DEN",
"sr_id": "sr:competitor:4418"
}
}
},
{
"id": "0c9102ea-9fe8-4900-9d33-8eab299cf9ce",
"name": "Chazz Surratt",
"jersey": "55",
"last_name": "Surratt",
"first_name": "Chazz",
"abbr_name": "C.Surratt",
"birth_date": "1997-02-16",
"weight": 233,
"height": 74,
"position": "LB",
"age": 26,
"birth_place": "Denver, NC, USA",
"high_school": "East Lincoln (NC)",
"college": "North Carolina",
"college_conf": "Atlantic Coast Conference",
"rookie_year": 2021,
"status": "played",
"sr_id": "sr:player:2198060",
"in_game_status": "active",
"draft": {
"year": 2021,
"round": 3,
"number": 78,
"team": {
"id": "33405046-04ee-4058-a950-d606f8c30852",
"name": "Vikings",
"market": "Minnesota",
"alias": "MIN",
"sr_id": "sr:competitor:4423"
}
}
},
Use Case: You could integrate this feed to provide real-time updates to users about player statuses — whether players are active, probable, benched, or out. This allows fantasy league participants to be notified of players on when a player on their roster may be out of the game due to an injury or benching.
Player Participation and In-Game Player Status
- The
statusrefers to the overall game status of a player, indicating whether they were deactivated, did not play (dnp), played, or started in the game. - The
in_game_statusindicates the real-time condition of a player during the game, such as whether they are active, probable, questionable, doubtful, out, benched, or unknown.
Tip - Leveraging In-Game Player Statuses
You can use the Game Roster feed to track in-game player status updates with the
in_game_statusdatapoint. This status updates in real-time to show whether players areactive,probable,questionable,doubtful,benched,out, orunknownduring the game.
Depth Charts
NFL depth charts illustrate players on a team in order of their position and playing status. They show the starters and the backup players for each position, indicating who would step in during a game if a starter were unavailable due to injury or other reasons. This helps teams organize their roster effectively for game planning and provides fans and analysts insight into team strategies and player hierarchies.
The following shows the Minnesota Vikings' offensive depth chart for week 8 of the 2023 season, detailing starters and their backups for each position.
How to Access Depth Chart Data: You can access depth chart data using the Weekly Depth Charts feed. This endpoint provides depth chart information for each team for a given week.
Recommended Pull Frequency:
- Depth charts are updated shortly before each game, but may be updated during or post game.
- Pull every hour or less during the current week, depending on your use case.
- The TTL for this feed is 120 seconds.
Example - Weekly Depth Charts
{
"season": {
"id": "a538d200-e916-4272-aa07-b486094a1668",
"year": 2023,
"type": "REG",
"name": "REG"
},
"week": {
"id": "b97007d7-03b1-4ef9-8fb1-d96d7abdb722",
"sequence": 1,
"title": "1"
},
"teams": [
{
"id": "de760528-1dc0-416a-a978-b510d20692ff",
"name": "Cardinals",
"market": "Arizona",
"alias": "ARI",
"sr_id": "sr:competitor:4412",
"offense": [
{
"position": {
"name": "TE",
"players": [
{
"id": "de3421f7-2147-4835-89a5-724e87bad463",
"name": "Zach Ertz",
"jersey": "86",
"position": "TE",
"sr_id": "sr:player:827633",
"depth": 1
},
{
"id": "734d54cc-c869-4e2f-a60f-c59c493f5110",
"name": "Trey McBride",
"jersey": "85",
"position": "TE",
"sr_id": "sr:player:1473622",
"depth": 2
},
{
"id": "d0f9112d-2496-450a-9fc5-d2d01b4d2454",
"name": "Geoff Swaim",
"jersey": "87",
"position": "TE",
"sr_id": "sr:player:855676",
"depth": 3
},
{
"id": "a01b7698-d67f-4b60-b2fb-4c667336b718",
"name": "Elijah Higgins",
"jersey": "84",
"position": "TE",
"sr_id": "sr:player:1696253",
"depth": 4
}
]
}
},
{
"position": {
"name": "LG",
"players": [
{
"id": "00fdaebe-c8f6-43fa-addb-6a57dc6c5969",
"name": "Elijah Wilkinson",
"jersey": "65",
"position": "OL",
"sr_id": "sr:player:1137927",
"depth": 1
},
{
"id": "f1f4a350-cc5f-43a2-bde1-829058d6c338",
"name": "Carter O'Donnell",
"jersey": "61",
"position": "OL",
"sr_id": "sr:player:2040355",
"depth": 2
}
]
}
},
{
"position": {
"name": "RG",
"players": [
{
"id": "3a39ab56-f188-4924-862d-c79ce67a3420",
"name": "Will Hernandez",
"jersey": "76",
"position": "OL",
"sr_id": "sr:player:1188454",
"depth": 1
},
{
"id": "a3f67680-66f1-4efc-b21b-badd19467cc9",
"name": "Trystan Colon",
"jersey": "63",
"position": "OL",
"sr_id": "sr:player:1220306",
"depth": 2
}
]
}
},
{
"position": {
"name": " WR",
"players": [
{
"id": "7fc949b6-a1cb-4f9d-a06d-b65773409a44",
"name": "Zach Pascal",
"jersey": "0",
"position": "WR",
"sr_id": "sr:player:1132243",
"depth": 1
},
{
"id": "b91be982-fccd-448e-869b-e9b5148a1730",
"name": "Michael Wilson",
"jersey": "14",
"position": "WR",
"sr_id": "sr:player:1438988",
"depth": 2
}
]
}
},
{
"position": {
"name": "RT",
"players": [
{
"id": "b46d84ef-d811-47f5-a6e2-586bfbc8f548",
"name": "Paris Johnson Jr.",
"jersey": "70",
"position": "OL",
"sr_id": "sr:player:2001137",
"depth": 1
},
{
"id": "d96246d7-aa2c-4d05-9c58-8d6bc5e20cdf",
"name": "Kelvin Beachum",
"jersey": "68",
"position": "OL",
"sr_id": "sr:player:829037",
"depth": 2
}
]
}
},
{
"position": {
"name": "LT",
"players": [
{
"id": "90d9c6b2-3970-45e1-a558-b68a977a8995",
"name": "D.J. Humphries",
"position": "OL",
"sr_id": "sr:player:834537",
"depth": 1
},
{
"id": "2f58f750-e8f3-11ed-bb4e-979e408fed0c",
"name": "Ilm Manning",
"jersey": "73",
"position": "OL",
"sr_id": "sr:player:1477174",
"depth": 2
},
{
"id": "adb1984e-17b1-4efc-9af9-94cec5835c91",
"name": "Jackson Barton",
"jersey": "66",
"position": "OL",
"sr_id": "sr:player:1227640",
"depth": 3
}
]
}
},
{
"position": {
"name": "WR",
"players": [
{
"id": "feeee40a-dd63-41a7-89cd-6c95b5456833",
"name": "Hollywood Brown",
"position": "WR",
"sr_id": "sr:player:1234416",
"depth": 1
}
]
}
},
This code sample outlines the Arizona Cardinals' offensive lineup for a specific week during the 2023 NFL regular season, showing the depth chart for positions like Tight End (TE), Left Guard (LG), Right Guard (RG), Wide Receiver (WR), Right Tackle (RT), and Left Tackle (LT). It lists primary and backup players for each position, providing unique player IDs, names, jersey numbers, and their specific roles within the team.
Transactions
NFL transactions refer to the movements of players between teams through trades, free agency signings, releases, or waivers. A transaction becomes official when it is processed by the league office and reported in the NFL's daily transaction list.
How to Access Transactions: You can access daily transaction updates using the Daily Transactions feed, which provides details of all transactions added or edited throughout each league-defined day.
Waiving Players
In the NFL, the term "waive" refers to a process where players with less than four years of service time are put on the waiver wire, making them available for other teams to claim under the same contract conditions. If unclaimed, these players become unrestricted free agents. This system allows teams to potentially pick up young talent that has been let go by other teams.
Recommended Pull Frequency:
- The feed updates in real-time as transactions occur.
- Depending on your needs, you might consider pulling data hourly.
- The TTL for this feed is 300 seconds.
Tip - Track Effective Dates
To ensure accuracy in tracking player movements, always check the
effective_datein transaction data as it specifies when changes officially take place.
Example - Daily Transactions:
{
"league": {
"id": "3c6d318a-6164-4290-9bbc-bf9bb21cc4b8",
"name": "National Football League",
"alias": "NFL"
},
"start_time": "2023-08-17T04:00:00Z",
"end_time": "2023-08-18T03:59:59Z",
"players": [
{
"id": "f1236815-5ed7-4bab-808f-700c4516fd7d",
"name": "Ja'Marcus Bradley",
"first_name": "Ja'Marcus",
"last_name": "Bradley",
"position": "WR",
"sr_id": "sr:player:2040191",
"transactions": [
{
"id": "0677b0e0-3d41-11ee-a025-05d4d8fdbbd5",
"desc": "The Pittsburgh Steelers waived WR Ja'Marcus Bradley due to injury.",
"effective_date": "2023-08-17",
"last_modified": "2023-08-17T21:01:37Z",
"transaction_type": "Waived-Injury",
"transaction_code": "WAI",
"transaction_year": 2023,
"status_before": "IR",
"status_after": "UFA",
"from_team": {
"id": "cb2f9f1f-ac67-424e-9e72-1475cb0ed398",
"name": "Steelers",
"market": "Pittsburgh",
"alias": "PIT",
"sr_id": "sr:competitor:4345"
}
}
]
},
{
"id": "932140a0-2d8e-11ee-8d33-c7332e65261c",
"name": "Wayne Taulapapa",
"first_name": "Wayne",
"last_name": "Taulapapa",
"position": "RB",
"sr_id": "sr:player:1566260",
"transactions": [
{
"id": "082538a0-3d27-11ee-8e11-abd7da5a6b0b",
"desc": "The Seattle Seahawks waived RB Wayne Taulapapa.",
"effective_date": "2023-08-17",
"last_modified": "2023-08-17T17:54:14Z",
"transaction_type": "Waived",
"transaction_code": "WA",
"transaction_year": 2023,
"status_before": "ACT",
"status_after": "UFA",
"from_team": {
"id": "3d08af9e-c767-4f88-a7dc-b920c6d2b4a8",
"name": "Seahawks",
"market": "Seattle",
"alias": "SEA",
"sr_id": "sr:competitor:4430"
}
}
]
},
{
"id": "9e82eb73-21f0-469a-ac85-b4fde70a6a4e",
"name": "Kemon Hall",
"first_name": "Kemon",
"last_name": "Hall",
"position": "CB",
"sr_id": "sr:player:1233490",
"transactions": [
{
"id": "0aaa1a80-3d42-11ee-b431-29a52304560d",
"desc": "The Los Angeles Chargers placed CB Kemon Hall on the IR, after being waived due to injury.",
"effective_date": "2023-08-17",
"last_modified": "2023-08-17T21:08:43Z",
"transaction_type": "Placed on Injured Reserve",
"transaction_code": "IR",
"transaction_year": 2023,
"status_before": "UFA",
"status_after": "IR",
"to_team": {
"id": "1f6dcffb-9823-43cd-9ff4-e7a8466749b5",
"name": "Chargers",
"market": "Los Angeles",
"alias": "LAC",
"sr_id": "sr:competitor:4429"
}
}
]
},
{
"id": "11e6adfb-8144-4990-adc2-bfcfe905889b",
"name": "Buddy Johnson",
"first_name": "Buddy",
"last_name": "Johnson",
"position": "LB",
"sr_id": "sr:player:2198688",
"transactions": [
{
"id": "1d472570-3d1a-11ee-b772-2d653603155d",
"desc": "The Chicago Bears waived LB Buddy Johnson.",
"effective_date": "2023-08-17",
"last_modified": "2023-08-17T16:21:48Z",
"transaction_type": "Waived-Injury",
"transaction_code": "WAI",
"transaction_year": 2023,
"status_before": "ACT",
"status_after": "UFA",
"from_team": {
"id": "7b112545-38e6-483c-a55c-96cf6ee49cb8",
"name": "Bears",
"market": "Chicago",
"alias": "CHI",
"sr_id": "sr:competitor:4391"
}
}
]
},
{
"id": "2f243870-eb74-11ed-aecd-85bc826ed43e",
"name": "Trevor Reid",
"first_name": "Trevor",
"last_name": "Reid",
"position": "T",
"sr_id": "sr:player:2067285",
"transactions": [
{
"id": "273bb710-3d35-11ee-9cfd-8563fd4ebfa4",
"desc": "The Atlanta Falcons signed T Trevor Reid.",
"effective_date": "2023-08-17",
"last_modified": "2023-08-17T19:35:38Z",
"transaction_type": "Signed",
"transaction_code": "SGN",
"transaction_year": 2023,
"status_before": "UFA",
"status_after": "ACT",
"to_team": {
"id": "e6aa13a4-0055-48a9-bc41-be28dc106929",
"name": "Falcons",
"market": "Atlanta",
"alias": "ATL",
"sr_id": "sr:competitor:4393"
}
}
]
},
This code sample illustrates how you can leverage the NFL's transaction feed to track various player movements within the league. It provides detailed information about players such as Ja'Marcus Bradley, Wayne Taulapapa, and Kemon Hall, including their transaction history, statuses before and after transactions, and the teams involved.
Use Case: As a developer working on a sports news aggregation app, you can use this NFL transaction feed to provide real-time updates on player moves and status changes directly on your platform. This keeps your users informed with the latest happenings in the league, especially during the active trading and signing periods. For example, you could highlight major transactions like trades, signings, or injury-related changes, enhancing the timeliness and relevance of the content on your app.
Transaction and Code Types
For the full list of transaction and code types, visit our NFL FAQ.
Free Agents
Free agents are players who are not currently under contract with any team, allowing them to sign with any team of their choosing. The Free Agents endpoint provides detailed player information for all current free agents in the league.
Recommended Pull Frequency
- Updates are made in realtime as changes are made to rosters or player profiles.
- Pull every hour or less depending on your use case.
- The TTL for this feed is 300 seconds.
Free Agents Response Example
{
"league": {
"id": "3c6d318a-6164-4290-9bbc-bf9bb21cc4b8",
"name": "National Football League",
"alias": "NFL",
"free_agents": [
{
"id": "0009fa10-ca24-11ec-9f1c-b7114d38a85b",
"full_name": "Chris Owens",
"first_name": "Chris",
"last_name": "Owens",
"abbr_name": "C.Owens",
"height": 75,
"weight": 305.0,
"jersey_number": "0",
"college": "Alabama",
"high_school": "Lamar (TX)",
"birth_place": "Arlington, TX, USA",
"updated": "2022-08-25T12:36:31Z"
},
{
"id": "000bc6c6-c9a8-4631-92d6-1cea5aaa1644",
"full_name": "Austin Pasztor",
"first_name": "Austin",
"last_name": "Pasztor",
"abbr_name": "A.Pasztor",
"height": 79,
"weight": 305.0,
"jersey_number": "0",
"college": "Virginia",
"high_school": "Glendale (Ontario)",
"birth_place": "Langton, ON, CAN",
"updated": "2022-04-02T15:16:34Z"
},
{
"id": "0015e8b2-924c-4dad-923b-52a804a584b1",
"full_name": "Faquan Calhoun",
"first_name": "Faquan",
"last_name": "Calhoun",
"abbr_name": "F.Calhoun",
"height": 73,
"weight": 205.0,
"jersey_number": "0",
"college": "Cumberland College",
"birth_place": "Lebanon, KY, USA",
"updated": "2022-04-10T01:08:03Z"
},
{
"id": "001fc9cd-129f-4ad1-a3e4-212e5398add5",
"full_name": "Anthony Ezeakunne",
"first_name": "Anthony",
"last_name": "Ezeakunne",
"abbr_name": "A.Ezeakunne",
"height": 76,
"weight": 235.0,
"jersey_number": "0",
"college": "Chapman",
"high_school": "West Torrance (CA)",
"birth_place": "Wilmington, CA, USA",
"updated": "2022-04-06T18:14:05Z"
},
{
"id": "fffee080-04ff-11ef-8a9a-5f3b29e3b4c8",
"full_name": "Tulu Griffin",
"first_name": "Tulu",
"last_name": "Griffin",
"abbr_name": "T.Griffin",
"height": 70,
"weight": 181.0,
"college": "Mississippi State",
"high_school": "Philadelphia (MS)",
"birth_place": "Philadelphia, MS, USA",
"updated": "2025-05-05T20:02:42Z"
}
]
},
"_comment": "Generation started @ 2025-05-28 15:56:39 UTC ended @ 2025-05-28 15:56:40 UTC"
}
Integrate the Free Agents endpoint to track available players for potential team signings or roster updates.
Injury Data
Accessing injury data is crucial for managing NFL rosters, as it helps teams assess player availability and make strategic decisions.
How to Access Injury Data: You can access injury data using the Weekly Injuries feed. This endpoint provides a list of injured players for each team for a given week, including practice status.
Recommended Pull Frequency:
- Injuries are made available depending on the day of a game.
- See our Data Entry Workflow for specific timings on injury updates.
- Pull every hour or less during the current week, depending on your use case.
- The TTL for this feed is 120 seconds.
Example - Weekly Injuries:
{
"season": {
"id": "a538d200-e916-4272-aa07-b486094a1668",
"year": 2023,
"type": "REG",
"name": "REG"
},
"week": {
"id": "9d81d807-ef3c-4335-94c4-981b376df6bc",
"sequence": 10,
"title": "10"
},
"teams": [
{
"id": "4254d319-1bc7-4f81-b4ab-b5e6f3402b69",
"name": "Buccaneers",
"market": "Tampa Bay",
"alias": "TB",
"sr_id": "sr:competitor:4388",
"players": [
{
"id": "ec558188-4bc5-4e5a-9035-dca1b46a49d4",
"name": "Logan Hall",
"jersey": "90",
"position": "DL",
"sr_id": "sr:player:1500975",
"injuries": [
{
"status": "Questionable",
"status_date": "2023-11-10T00:00:00+00:00",
"practice": {
"status": "Full Participation In Practice"
},
"primary": "Groin"
}
]
},
{
"id": "95242131-623b-41d0-8898-9d6f71da56f7",
"name": "Josh Hayes",
"jersey": "32",
"position": "DB",
"sr_id": "sr:player:1249510",
"injuries": [
{
"status": "Out",
"status_date": "2023-11-10T00:00:00+00:00",
"practice": {
"status": "Did Not Participate In Practice"
},
"primary": "Concussion"
}
]
},
{
"id": "9a011241-f4b3-403a-af70-c9cdfd177054",
"name": "Trey Palmer",
"jersey": "10",
"position": "WR",
"sr_id": "sr:player:1694071",
"injuries": [
{
"status": "Questionable",
"status_date": "2023-11-10T00:00:00+00:00",
"practice": {
"status": "Full Participation In Practice"
},
"primary": "Neck"
}
]
},
{
"id": "4c6f79d0-d3dd-11ec-8afa-57d9afd0ecba",
"name": "Deven Thompkins",
"jersey": "83",
"position": "WR",
"sr_id": "sr:player:1478034",
"injuries": [
{
"status_date": "2023-11-10T00:00:00+00:00",
"practice": {
"status": "Full Participation In Practice"
},
"primary": "Personal"
}
]
},
{
"id": "503eb9a7-83ed-4b96-b0f2-7afe4920bde9",
"name": "Vita Vea",
"jersey": "50",
"position": "DL",
"sr_id": "sr:player:1226254",
"injuries": [
{
"status_date": "2023-11-10T00:00:00+00:00",
"practice": {
"status": "Full Participation In Practice"
},
"primary": "Groin"
}
]
},
This JSON code sample returns detailed injury updates for NFL players on a team-by-team basis. It specifically lists the injuries for Tampa Bay Buccaneers players during the 10th week of the 2023 NFL season, detailing each player's injury status, participation in practice, and the type of injury sustained. This data is crucial for applications focusing on sports management, betting, or fan engagement, allowing you to integrate real-time health information of players into their platforms.
The following image visualizes this data.
Daily Change Log
The Daily Change Log endpoint provides an efficient way to monitor daily updates within the NFL API, including roster adjustments, transactions, and corrections to player injury details, without exhausting your API call quota.
The table below outlines scenarios and use cases for utilizing the Daily Change Log based on team roster and player updates.
| Data | Use Case |
|---|---|
| Team Rosters | Use this data to keep track of adjustments like player trades, contract signings, or releases. |
| Game Rosters | Useful for verifying rosters after a game or adjustments to player participation. |
| Transactions | Observe adjustments or corrections to transaction data. |
| Injuries | Observe adjustments or corrections to player injury data. |
| Depth Charts | Verify or track adjustments to team depth charts. |
Steps:
-
Identify Change Types: First, review the Daily Change Log to identify the types of changes reported. These could be related to games, players, or teams. Each entry in the log will list relevant IDs (game, player, or team ID), depending on the type of change.
-
Use IDs to Retrieve Specifics:
- Game Roster Changes: If the ID is found within the "results" node, this can indicate a post-game correction to the game roster. This ID is a game ID.
- Player and Team Changes: Similarly, IDs associated with players or teams indicate changes relevant to these entities, such as updates to team rosters.
-
Pull Detailed Data: Use the identified IDs to pull detailed information from the relevant feed. For example:
- Team Rosters Feed: If a team ID is mentioned, you can pull this feed to check for any updates to team rosters.
- Game Roster Feed: Use the game ID to retrieve updated game rosters and to see what specific data was altered.
-
Verify Changes: After pulling the detailed data from the relevant feeds, compare the newly retrieved data against previously stored data to verify the changes and update your records accordingly.
Update Frequency
TTL / Cache: 300 seconds
Data Updates:
- Entries populate live for changes to teams, players, game statistics, schedules, and standings.
- Start time of the log is 05:00:00 UTC; end time is 04:59:59 UTC
For optimal results, set a regular schedule to pull every 10 minutes or less (depending on your use case) to access the feed.
Data Entry Workflow Information
For detailed information on when roster, injury data, and player participation is added to the API, refer to the NFL Data Entry workflow documentation.
Updated 2 months ago