Developer Docs

The public data API.

Your tournament data, wherever you need it.

Read-only JSON for schedules, standings, matches, clubs and teams. No API key — access is controlled by the domain allowlist the organiser sets in Settings.

Introduction

Overview

Base URL: https://your-fixturepro-domain/api/public/tournaments/{tournamentId}. Replace {tournamentId} with the uuid from the tournament's public page URL (/t/{tournamentId}/…), also shown in Settings → Public sharing & data API.

  • All endpoints are GET, read-only and return JSON.
  • Only published tournaments are served; others return 404.
  • Timestamps are ISO-8601; match times are wall-clock times stored as UTC.
Access

Access & authentication

There are no keys or tokens. Each request must carry an Origin or Referer header whose host is on the tournament's allowlist.

  • Add hosts in Settings → Allowed domains. Matching is exact on the host — ports are ignored and subdomains are not included.
  • An empty allowlist blocks everyone (sharing is opt-in).
  • Browsers send Origin automatically on cross-site fetches. Server-to-server calls without either header get 403, so this is a browser-widget API rather than a back-end integration API.
Get going

Quickstart

Allowlist your host, then fetch the schedule. The curl form sets the header by hand to simulate a browser on that host.

curl
curl -s \
  -H "Origin: https://scoreboard.example" \
  "https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/schedule?date=all"
JavaScript (browser)
// Runs in a browser on an allowlisted domain — Origin is added for you.
const res = await fetch('https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/schedule?date=all')
const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
console.log(data.totalMatches)
Format

Response envelope

Every endpoint — success or failure — returns the same envelope, so one parser handles everything.

Shape
{
  success: boolean
  data:    T | null          // endpoint payload; null on error
  error:   { code: string, message: string } | null
  meta:    { generatedAt: string }   // ISO-8601, server time
}
Error example
{
  "success": false,
  "data": null,
  "error": {
    "code": "origin_not_allowed",
    "message": "This domain is not on the tournament's allowlist."
  },
  "meta": { "generatedAt": "2026-10-24T02:30:00.000Z" }
}

Branch on success and error.code, never on the message text.

Reference

Errors

StatusCodeWhenFix
403origin_not_allowedThe Origin/Referer host is not on the allowlist, is missing, or the allowlist is empty.Add the exact host in Settings → Allowed domains and call from a browser on that host.
404tournament_not_foundUnknown tournament id, or the tournament is not published.Check the uuid in the public page URL.
404match_not_foundThe match id does not belong to this tournament.Take ids from /schedule.
404club_not_foundThe club id does not belong to this tournament.Take ids from /clubs.
404team_not_foundThe team id does not belong to this tournament.Take ids from /clubs teams[].
Behaviour

Caching & CORS

  • Success responses send Cache-Control: public, max-age=60. Errors send no-store and Vary: Origin.
  • Allowed requests echo your origin in Access-Control-Allow-Origin. An OPTIONS preflight returns 204 with the same headers for allowed origins and 403 otherwise.
  • Data changes show up within about a minute; polling faster gains nothing.
Reference

Endpoint reference

Paths are relative to /api/public/tournaments/{tournamentId}.

GET/schedule

Schedule

Fixtures grouped by match day, then by phase or bracket section.

Parameters
NameTypeDescription
leagueuuidOnly fixtures of this league.
divisionstringDivision NAME as the public pages show it (URL-encoded).
rounduuidOnly fixtures of this round (phase id).
dateyyyy-mm-dd | allOne UTC match day, or every day. Absent = every day.
Response fields (inside data)
FieldTypeDescription
tournamentobjectid, name, format, status.
days[].datestring | nullUTC match day; null = TBC.
days[].labelstringDisplay label, e.g. "Sat 19 Sep".
days[].sections[]object[]Phase or bracket groups.
…sections[].kind"phase" | "bracket"Whether the section is a league/group round or a knockout bracket.
…sections[].titlestringRound name, or the bracket name for knockouts.
…sections[].phaseId / phaseType / roundNumberuuid | string | number | nullRound context; null on bracket sections.
…sections[].divisionName / leagueNamestring | nullDivision and league the section belongs to; null on bracket sections.
…sections[].bracketIduuid | nullThe bracket id; null on phase sections.
…sections[].matches[]object[]The fixtures, below.
…matches[].iduuidPass to /matches/{matchId}.
…matches[].source"league" | "bracket"League/group fixture or cup knockout fixture.
…matches[].statusstringscheduled | in_progress | completed | abandoned.
…matches[].scheduledAtstring | nullWall-clock time stored as UTC.
…matches[].matchNonumber | nullOrganiser-set Match No. (null when not numbered). Within a section, numbered matches come first by this number, then the rest by time.
…matches[].homeTeam / awayTeam{ id, name } | nullnull while a knockout slot is still undecided.
…matches[].homeScore / awayScorenumber | nullnull until a score is recorded.
…matches[].homePenalties / awayPenaltiesnumber | nullPenalty shoot-out result; knockout matches only, otherwise null.
…matches[].winnerIduuid | nullWinning team id for knockout matches; null for league fixtures.
…matches[].venue{ id, name, address } | nullLocation: the venue where the match is played; address may be null.
…matches[].pitch{ id, name } | nullLocation detail: the pitch within the venue (e.g. "Pitch 1").
…matches[].phaseId / phaseName / phaseType / roundNumberuuid | string | number | nullLeague round context (phaseId is the round id); null for knockout.
…matches[].divisionId / divisionNameuuid | string | nullDivision the match resolves to; null for knockout.
…matches[].leagueId / leagueNameuuid | string | nullLeague the match resolves to; null for knockout.
…matches[].bracketId / bracketNameuuid | string | nullBracket context; null for league fixtures.
…matches[].round / matchNumbernumber | nullKnockout round and bracket position (not the organiser Match No.); null for league fixtures.
totalMatchesnumberFixtures across all returned days.

Errors: 403 origin_not_allowed · 404 tournament_not_found

curl
curl -s \
  -H "Origin: https://scoreboard.example" \
  "https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/schedule?division=Division%201&date=2026-09-26"
JavaScript
const res = await fetch('https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/schedule?division=Division%201&date=2026-09-26')
const { data } = await res.json()
Example response
{
  "success": true,
  "data": {
    "tournament": { "id": "t-uuid", "name": "Autumn Cup", "format": "league", "status": "ongoing" },
    "days": [{
      "date": "2026-09-26",
      "label": "Sat 26 Sep",
      "sections": [{
        "kind": "phase", "title": "Round 1", "phaseId": "round-uuid", "phaseType": "league",
        "roundNumber": 1, "divisionName": "Division 1", "leagueName": "Under-15 Male", "bracketId": null,
        "matches": [{
          "id": "match-uuid", "source": "league", "status": "in_progress",
          "scheduledAt": "2026-09-26T09:00:00.000Z", "matchNo": 1,
          "homeScore": 2, "awayScore": 1,
          "homePenalties": null, "awayPenalties": null, "winnerId": null,
          "homeTeam": { "id": "team-uuid", "name": "Arsenal A" },
          "awayTeam": { "id": "team-uuid-2", "name": "Chelsea A" },
          "venue": { "id": "venue-uuid", "name": "River Valley HS", "address": "1 Stadium Rd" },
          "pitch": { "id": "pitch-uuid", "name": "Pitch 1" },
          "phaseId": "round-uuid", "phaseName": "Round 1", "phaseType": "league", "roundNumber": 1,
          "divisionName": "Division 1", "divisionId": "div-uuid",
          "leagueName": "Under-15 Male", "leagueId": "league-uuid",
          "bracketId": null, "bracketName": null, "round": null, "matchNumber": null
        }]
      }]
    }],
    "totalMatches": 1
  },
  "error": null,
  "meta": { "generatedAt": "2026-10-24T02:30:00.000Z" }
}
GET/standings

Standings

League tables per division; cup tournaments add group tables and brackets.

Parameters
NameTypeDescription
leagueuuidOnly divisions of this league.
divisionstringDivision NAME (URL-encoded).
rounduuidOnly this round (phase id).
Response fields (inside data)
FieldTypeDescription
groups[]object[]One table per division.
groups[].badge"live" | "final" | nulllive while a match is in progress.
groups[].rows[]object[]position, teamId, teamName, played, won, drawn, lost, goalsFor, goalsAgainst, goalDifference, points.
groups[].rows[].livebooleanTeam has a match in progress.
groups[].rows[].form("W"|"D"|"L")[]Recent results.
groups[].rows[].zone"promotion" | "relegation" | nullTable zone.
promotedCount / relegatedCountnumberTeams promoted / relegated per division table.
cupGroups[]object[]Cup group tables: id, title, divisionId, leagueId, leagueName, tierName, badge, advanceCount, rows[] (same row shape). Empty on leagues.
brackets[]object[]Knockout brackets: id, name, positionRangeStart/End, leagueId, tierName, matches[] (id, round, matchNumber, scores, penalties, status, winnerId, homeTeam, awayTeam, homeSource, awaySource). Empty on leagues.
cupAdvancePerGroupnumberTop-N positions per cup group that advance; 0 on leagues.

Errors: 403 origin_not_allowed · 404 tournament_not_found

curl
curl -s \
  -H "Origin: https://scoreboard.example" \
  "https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/standings?league=league-uuid"
JavaScript
const res = await fetch('https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/standings?league=league-uuid')
const { data } = await res.json()
Example response
{
  "success": true,
  "data": {
    "tournament": { "id": "t-uuid", "name": "Autumn Cup", "format": "league", "status": "ongoing" },
    "groups": [{
      "id": "div-uuid", "title": "Division 1", "leagueName": "Under-15 Male",
      "divisionId": "div-uuid", "leagueId": "league-uuid", "badge": "live",
      "rows": [{
        "position": 1, "teamId": "team-uuid", "teamName": "Arsenal A",
        "played": 3, "won": 3, "drawn": 0, "lost": 0,
        "goalsFor": 9, "goalsAgainst": 2, "goalDifference": 7, "points": 9,
        "live": true, "form": ["W", "W", "W"], "zone": "promotion"
      }]
    }],
    "promotedCount": 1, "relegatedCount": 1,
    "cupGroups": [], "brackets": [], "cupAdvancePerGroup": 0
  },
  "error": null,
  "meta": { "generatedAt": "2026-10-24T02:30:00.000Z" }
}
GET/filters

Filters

Filter-bar options: every league, division and round — including ones with no fixtures yet.

Response fields (inside data)
FieldTypeDescription
leagues[]{ id, name }Pass id as ?league=.
divisions[]{ id, name, leagueId, tierName }Pass name as ?division=; leagueId lets you narrow the list when a league is chosen.
rounds[]{ id, name, roundNumber }Pass id as ?round=.

Errors: 403 origin_not_allowed · 404 tournament_not_found

curl
curl -s \
  -H "Origin: https://scoreboard.example" \
  "https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/filters"
JavaScript
const res = await fetch('https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/filters')
const { data } = await res.json()
Example response
{
  "success": true,
  "data": {
    "leagues": [{ "id": "league-uuid", "name": "Under-15 Male" }],
    "divisions": [{ "id": "div-uuid", "name": "Division 3", "leagueId": "league-uuid", "tierName": null }],
    "rounds": [{ "id": "round-uuid", "name": "Round 1", "roundNumber": 1 }]
  },
  "error": null,
  "meta": { "generatedAt": "2026-10-24T02:30:00.000Z" }
}
GET/matches/{matchId}

Match detail

One match with its event timeline.

Parameters
NameTypeDescription
matchIduuid (path)From /schedule matches[].id.
Response fields (inside data)
FieldTypeDescription
matchobjectSame shape as a /schedule match, including venue, pitch and matchNo.
events[]object[]eventType, minute, periodNum, notes, teamId, teamName.
events[].playerNamestring | nullOnly while the organiser enables player names.
events[].playerNumbernumber | nullThe player’s squad number; same condition as playerName.

Errors: 403 origin_not_allowed · 404 tournament_not_found · 404 match_not_found

curl
curl -s \
  -H "Origin: https://scoreboard.example" \
  "https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/matches/{matchId}"
JavaScript
const res = await fetch('https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/matches/{matchId}')
const { data } = await res.json()
Example response
{
  "success": true,
  "data": {
    "match": {
      "id": "match-uuid", "source": "league", "status": "completed",
      "scheduledAt": "2026-09-26T09:00:00.000Z", "matchNo": 1,
      "homeScore": 5, "awayScore": 2,
      "homeTeam": { "id": "team-uuid", "name": "Arsenal A" },
      "awayTeam": { "id": "team-uuid-2", "name": "Chelsea A" },
      "venue": { "id": "venue-uuid", "name": "River Valley HS", "address": null },
      "pitch": { "id": "pitch-uuid", "name": "Pitch 1" }
      // …remaining fields as in /schedule
    },
    "events": [{
      "id": "event-uuid", "eventType": "goal", "minute": 12, "periodNum": 1,
      "notes": null, "teamId": "team-uuid", "teamName": "Arsenal A", "playerName": null, "playerNumber": null
    }]
  },
  "error": null,
  "meta": { "generatedAt": "2026-10-24T02:30:00.000Z" }
}
GET/clubs

Clubs

Participating clubs with their teams.

Parameters
NameTypeDescription
lettera–zCase-insensitive initial; anything else returns all.
Response fields (inside data)
FieldTypeDescription
[].id / name / logoUrlstringClub identity; logoUrl may be null.
[].teams[]{ id, name }Team ids for /teams/{teamId}.

Errors: 403 origin_not_allowed · 404 tournament_not_found

curl
curl -s \
  -H "Origin: https://scoreboard.example" \
  "https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/clubs?letter=a"
JavaScript
const res = await fetch('https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/clubs?letter=a')
const { data } = await res.json()
Example response
{
  "success": true,
  "data": [{ "id": "club-uuid", "name": "Arsenal FC", "logoUrl": null, "teams": [{ "id": "team-uuid", "name": "Arsenal A" }] }],
  "error": null,
  "meta": { "generatedAt": "2026-10-24T02:30:00.000Z" }
}
GET/clubs/{clubId}

Club detail

One club with its teams.

Parameters
NameTypeDescription
clubIduuid (path)From /clubs [].id.
Response fields (inside data)
FieldTypeDescription
id / name / logoUrl / teams[]objectAs in /clubs.

Errors: 403 origin_not_allowed · 404 tournament_not_found · 404 club_not_found

curl
curl -s \
  -H "Origin: https://scoreboard.example" \
  "https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/clubs/{clubId}"
JavaScript
const res = await fetch('https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/clubs/{clubId}')
const { data } = await res.json()
Example response
{
  "success": true,
  "data": { "id": "club-uuid", "name": "Arsenal FC", "logoUrl": null, "teams": [{ "id": "team-uuid", "name": "Arsenal A" }] },
  "error": null,
  "meta": { "generatedAt": "2026-10-24T02:30:00.000Z" }
}
GET/teams/{teamId}

Team detail

Team, club, division and squad (privacy-toggled).

Parameters
NameTypeDescription
teamIduuid (path)From /clubs [].teams[].id.
Response fields (inside data)
FieldTypeDescription
team / club / divisionobjectdivision includes leagueName; club or division may be null.
showPublicPlayerNamesbooleanOrganiser privacy toggle.
players[]object[]Empty unless the toggle is on: id, name, squadNumber, position, photoUrl.

Errors: 403 origin_not_allowed · 404 tournament_not_found · 404 team_not_found

curl
curl -s \
  -H "Origin: https://scoreboard.example" \
  "https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/teams/{teamId}"
JavaScript
const res = await fetch('https://your-fixturepro-domain/api/public/tournaments/{tournamentId}/teams/{teamId}')
const { data } = await res.json()
Example response
{
  "success": true,
  "data": {
    "team": { "id": "team-uuid", "name": "Arsenal A" },
    "club": { "id": "club-uuid", "name": "Arsenal FC" },
    "division": { "id": "div-uuid", "name": "Division 1", "leagueName": "Under-15 Male" },
    "showPublicPlayerNames": false,
    "players": []
  },
  "error": null,
  "meta": { "generatedAt": "2026-10-24T02:30:00.000Z" }
}
Concepts

Filtering

Filters are optional and tolerant: an invalid or unknown value is ignored and you get unfiltered data, never an error. They combine freely.

  • date (/schedule only): yyyy-mm-dd or all. Unlike the schedule page, the API applies no default date.
  • league, division, round (/schedule, /standings): division is the NAME, URL-encoded (Division%201); one name spans same-named divisions across leagues. While any is active, knockout (bracket) matches are excluded.
  • letter (/clubs): one character a–z.
  • Discover valid values with /filters — it also lists leagues, divisions and rounds that have no fixtures yet.
Concepts

Match statuses

statusMeaning
scheduledNot started. Scores are null.
in_progressLive. Show a LIVE chip; scores update as the organiser records them.
completedFull time. Show an FT chip and the final score.
abandonedStopped before full time. Show an Abandoned chip; the score is the score at abandonment and is not counted in standings.
Data

Privacy

  • Squads: players in /teams/… is empty unless the organiser enabled “Show player names in public match events”. Photos also need “Also show player photos on the public team page”; photo urls are signed and expire after one hour.
  • Match events: playerName and playerNumber are null unless the names toggle is on.
  • Foreign ids: ids from another tournament return 404.
Recipe

Build a filter bar

Load options from /filters, then pass the chosen values to /schedule and /standings.

JavaScript
const BASE = 'https://your-fixturepro-domain/api/public/tournaments/{tournamentId}'

async function api(path) {
  const res = await fetch(BASE + path) // browser adds Origin automatically
  const body = await res.json()
  if (!body.success) throw new Error(body.error.code)
  return body.data
}

// 1. Filter bar
const { leagues, divisions, rounds } = await api('/filters')
const divisionsInLeague = (leagueId) => divisions.filter((d) => d.leagueId === leagueId)

// 2. Schedule for the chosen filters
const qs = new URLSearchParams({ league: leagueId, division: divisionName, date: 'all' })
const { days } = await api(`/schedule?${qs}`)

// 3. Standings with the same filters (date is ignored here)
const { groups } = await api(`/standings?${qs}`)

// 4. Poll at most once a minute — responses are cached for 60 s
Policy

Rate limits

Rate limiting is not implemented yet (tracked in the product backlog). Respect the 60-second cache window and avoid per-visitor polling loops.

History

Changelog

  • Match events gained playerNumber (squad number).
  • Added GET /filters (leagues, divisions, rounds).
  • Initial release: schedule, standings, matches, clubs, teams, with league/division/round/date filters.