UFL API Basics

This page covers the practical basics of the UFL API: authentication, URL structure, seasons and season types, formats, errors, cache behavior, and time values. The payloads themselves are covered in the scenario pages.

Authentication

Every request is authenticated with your API key in the x-api-key header:

GET https://api.sportradar.com/ufl/trial/v7/en/league/hierarchy.json
x-api-key: YOUR_API_KEY

Keep the key server-side; do not embed it in client applications.

Base URL and URL Structure

All requests follow one URL shape:

GET https://api.sportradar.com/ufl/{access_level}/v7/{language_code}/{feed}.{format}

access_level: trial or production, matching your key.
language_code: en (English).
format: json or xml. Both carry the same data on every feed.

Feeds are scoped five ways:

League-wide feeds live under /league/ (Hierarchy, Seasons, Teams)
Date-scoped feeds take a {year}/{month}/{day} trio (Daily Change Log, Daily Transactions)
Season-scoped feeds take a {season_year}/{season_type} pair (Season Schedule, Postgame Standings, Seasonal Statistics), with the weekly feeds adding a {week_number} (Weekly Schedule, Weekly Injuries, Weekly Depth Charts)
Entity-scoped feeds take a GUID (Game Boxscore, Play-by-Play, Roster, and Statistics by game ID; Team Roster by team ID; Player Profile by player ID; Tournament Schedule and Summary by tournament ID)
Convenience feeds need no parameters at all (Current Season Schedule, Current Week Schedule)

{week_number} is a zero-padded string (01 through 12): week one is 01, not 1.

UFL API Map

To make the most of the UFL API you will need a handful of parameters to build your calls. The map below shows which identifier each feed takes and where it comes from; every pill links to that feed's reference page.

Seasons and Season Types

{season_year} is the calendar year of the season. {season_type} selects the phase: REG (regular season) or PST (postseason). A PRE season type exists in the format but is never populated; the UFL does not play a preseason. Seasons lists every season on file; the 2026 entries:

{
  "league": {
    "id": "d441365f-cfab-49d6-9976-6c95d91fdef7",
    "name": "United Football League",
    "alias": "UFL"
  },
  "seasons": [
    {
      "id": "4123d3de-ea19-4e5a-9320-d29026eb3df6",
      "year": 2026,
      "start_date": "2026-06-06",
      "end_date": "2026-06-13",
      "status": "closed",
      "type": {
        "code": "PST"
      }
    },
    {
      "id": "4ee5ece0-6f0b-11f0-b1e6-2dad3ff60df1",
      "year": 2026,
      "start_date": "2026-03-27",
      "end_date": "2026-05-31",
      "status": "closed",
      "type": {
        "code": "REG"
      }
    }
  ]
}

<?xml version="1.0" ?>
<!-- Generation started @ 2026-06-14 10:13:45 +0000 -->
<league xmlns="http://feed.elasticstats.com/schema/football/seasons-v7.0.xsd" id="d441365f-cfab-49d6-9976-6c95d91fdef7" name="United Football League" alias="UFL">
  
  
  <!-- ... omitted for brevity -->
  <season id="4123d3de-ea19-4e5a-9320-d29026eb3df6" year="2026" start_date="2026-06-06" end_date="2026-06-13" status="closed">
    
    
    <type code="PST"/>
    
  
  </season>
  <season id="4ee5ece0-6f0b-11f0-b1e6-2dad3ff60df1" year="2026" start_date="2026-03-27" end_date="2026-05-31" status="closed">
    
    
    <type code="REG"/>
    
  
  </season>
  

</league>

The XML response is shown with earlier seasons omitted for brevity.

The regular season runs from late March through May; the postseason plays two playoff games and the United Bowl across two June weekends. Each season entry carries its own id, dates, and status.

Complete Responses

Feeds return the complete data set for their scope in a single response; there is no pagination. A full Season Schedule returns every game of the season (40 for the 2026 regular season), and Seasonal Statistics returns every player on the team in one payload.

Errors

Authentication failures return 403 with an HTML page, not a JSON or XML error object; branch on the status code:

<!DOCTYPE html>
      <html lang="en">
        <head>
          <meta charset="utf-8">
          <title>Authentication Error</title>
        </head>
        <body>
          <p>Authentication Error</p>
        </body>
      </html>

Rate-limit errors return 429 Too Many Requests; slow your request rate and retry, increasing the wait between attempts
404 indicates an unknown ID or path
Other statuses follow the Response Codes page

Cache Behavior

Each response carries a cache-control header stating how long the payload may be served from cache. TTLs are tiered by feed family and by game activity: 10 minutes on schedules with active games and on standings, 4 hours on the league catalog, statistics, profiles, and weekly report feeds, and status-tiered on the game feeds (down to 3 seconds while a game is in play). The per-feed chart is on the Update Frequencies page.

⚠️
A TTL Is Not a Polling Recommendation
A short TTL means the payload can change that often, not that you should request it that often. Check the header on each response you receive, and match your polling cadence to the freshness your product actually needs. Recommended cadences are on the Update Frequencies page and in each scenario's Best Practices.

Time Values

Timestamps are UTC ISO 8601 (scheduled values carry an explicit offset). Date-only fields such as season dates and birth dates follow local league convention and are not UTC-adjusted. The date-scoped feeds (Daily Change Log, Daily Transactions) use the league-defined day, which runs 04:00:00Z to 03:59:59Z: a transaction entered on a US evening belongs to that US date's feed even when its UTC timestamp has rolled past midnight. Plan date math accordingly.

Delivery Options

The feeds in this guide are RESTful pull feeds. Real-time push delivery is available through the Push Events and Push Statistics feeds; the Push Feeds page covers the connection workflow, and your Sportradar representative can add Push to your package.

Integration Resources

Interactive reference: every endpoint on the reference pages can be exercised against your key
Postman: fork the UFL collection from the public workspace
XSD schemas: the UFL v7 schema bundle describes the XML format
Simulations: replay past games on demand to exercise live-game handling at any time of year, including the Push feeds
MCP server: the Sportradar MCP server exposes the UFL feeds to AI-assisted development tools