Referees

What does the include do?

The referees include returns the match officials assigned to a fixture. Unlike the coaches include, this is a lean linking object, it does not embed the official's name or biographical data directly. You get IDs and a type, and need a separate lookup to get the person's details.

Why use referees?

• Match centre displays: Show who officiated a fixture

• Referee performance tracking: Combine with the standalone Referee endpoint's statistics to analyse card counts, penalties given, etc. per official

• Data consistency checks: Confirm which officials were assigned before publishing match reports

Requesting referees

https://api.sportmonks.com/v3/football/fixtures/{fixture_id}
?api_token=YOUR_TOKEN&include=referees

Response structure

{
  "data": {
    "id": 18535517,
    "name": "Celtic vs Rangers",
    "referees": [
      {
        "id": 2123470,
        "fixture_id": 18535517,
        "referee_id": 14468,
        "type_id": 6
      }
    ]
  }
}

Field descriptions

Field	Type	Description
id	integer	Unique identifier for this referee assignment record
fixture_id	integer	The fixture this assignment belongs to
referee_id	integer	Links to the full referee record, see below to resolve this to a name
type_id	integer	Which officiating role this person held, see table below

Referee type values

Confirmed via /core/types:

type_id	Role
6	Referee
7	1st Assistant
8	2nd Assistant
9	4th Official
10	VAR

Not all roles are guaranteed to appear, even in VAR-using leagues. Live testing on a Scottish Premiership fixture from a season when VAR was active returned only one entry (type_id: 6, the main Referee), with no 4th Official or VAR entry present. Don't assume a fixture will include all five roles, or that a missing VAR entry means VAR wasn't used, coverage depends on what data was tracked for that specific match.

Getting the referee's name

The fixture-level referees include only gives you referee_id. To resolve this to a name and profile, make a separate request to the standalone Referee endpoint:

https://api.sportmonks.com/v3/football/referees/{referee_id}
?api_token=YOUR_TOKEN

{
  "data": {
    "id": 14468,
    "sport_id": 1,
    "country_id": 1161,
    "city_id": null,
    "common_name": "J. Beaton",
    "firstname": "John",
    "lastname": "Beaton",
    "name": "John Beaton",
    "display_name": "J. Beaton",
    "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
    "height": null,
    "weight": null,
    "date_of_birth": null,
    "gender": null
  }
}

Code examples

JavaScript

const API_TOKEN = "YOUR_TOKEN";
const FIXTURE_ID = 18535517;

async function getFixtureReferee() {
  const fixtureUrl = `https://api.sportmonks.com/v3/football/fixtures/${FIXTURE_ID}`;
  const fixtureResponse = await fetch(`${fixtureUrl}?api_token=${API_TOKEN}&include=referees`);
  const fixture = (await fixtureResponse.json()).data;

  const mainReferee = fixture.referees.find(r => r.type_id === 6);
  if (!mainReferee) {
    console.log("No main referee assigned for this fixture.");
    return;
  }

  const refUrl = `https://api.sportmonks.com/v3/football/referees/${mainReferee.referee_id}`;
  const refResponse = await fetch(`${refUrl}?api_token=${API_TOKEN}`);
  const referee = (await refResponse.json()).data;

  console.log(`Referee: ${referee.display_name}`);
}

getFixtureReferee();

Python

import requests

API_TOKEN = "YOUR_TOKEN"
FIXTURE_ID = 18535517

fixture_url = f"https://api.sportmonks.com/v3/football/fixtures/{FIXTURE_ID}"
fixture = requests.get(fixture_url, params={
    "api_token": API_TOKEN,
    "include": "referees"
}).json()['data']

main_referee = next((r for r in fixture['referees'] if r['type_id'] == 6), None)

if main_referee:
    ref_url = f"https://api.sportmonks.com/v3/football/referees/{main_referee['referee_id']}"
    referee = requests.get(ref_url, params={"api_token": API_TOKEN}).json()['data']
    print(f"Referee: {referee['display_name']}")
else:
    print("No main referee assigned for this fixture.")

PHP

<?php

$apiToken = "YOUR_TOKEN";
$fixtureId = 18535517;

$fixtureUrl = "https://api.sportmonks.com/v3/football/fixtures/{$fixtureId}";
$fixtureParams = http_build_query(["api_token" => $apiToken, "include" => "referees"]);
$fixture = json_decode(file_get_contents("{$fixtureUrl}?{$fixtureParams}"), true)["data"];

$mainReferee = current(array_filter($fixture["referees"], fn($r) => $r["type_id"] === 6));

if ($mainReferee) {
    $refUrl = "https://api.sportmonks.com/v3/football/referees/{$mainReferee['referee_id']}";
    $refParams = http_build_query(["api_token" => $apiToken]);
    $referee = json_decode(file_get_contents("{$refUrl}?{$refParams}"), true)["data"];
    echo "Referee: {$referee['display_name']}\n";
} else {
    echo "No main referee assigned for this fixture.\n";
}

Best practices

1. Don't assume all five roles will be present. Filter for the type_id you actually need (usually 6, the main referee) rather than indexing by array position.

2. Cache referee profile lookups. A referee's biographical data doesn't change often, cache by referee_id rather than re-fetching on every fixture request.

3. Use referee statistics for performance tracking, not this include. If you're building card-count or penalty-given dashboards, use include=statistics.details.type on the standalone Referee endpoint instead.

Related includes

• Coaches - Similar fixture-level personnel include, but embeds full bio data directly (referees does not)

• Participants - Required for general match context

Summary

The referees include returns lean linking objects (referee_id, type_id) rather than full profiles, unlike coaches. Resolve referee_id via a separate call to the standalone Referee endpoint to get a name. Type values run from 6 (Referee) to 10 (VAR), but not all roles are guaranteed to appear on every fixture, even in leagues that use VAR.