# Get a fixture's officials

`GET /v1/fixtures/{id}/officials`

The persons who officiated the fixture (the referee, the assistant referees, the fourth
official) as known at `known_at`, as `mo_<digits>` match officials, each a citable record
with its own identifier and versions. Governed by the `context` dataset: the organization needs a
current `context` grant (and the `read:entities` scope) whose competitions include the
fixture's; an unknown fixture is `404`, a fixture outside the grant `403 not-entitled`
(`restriction: competition`).

- **Versions and `known_at`.** Every official is the highest version recorded by the
  cutoff; an official the source's newer capture of the match no longer lists is
  retracted and left out from then on.
- **Roles.** `referee`, `assistant_referee` (`role_order` 1 and 2 for the first and
  second assistant), `fourth_official`; `video_assistant` is in the vocabulary, but no
  source sends it today. Order: referee, assistants by `role_order`, fourth official.
- **Identifiers.** `person_id` is the canonical person at the cutoff; a referee the
  source names is the same person as FootyStats' referee of that name. An official known
  only from sources you may not be served is left out, as `GET /v1/persons/{id}` answers
  `404`.
- **Coverage.** The source lists officials from 2009/10, in some seasons only part of
  the roles: `unavailable` means no official is known for the fixture at the cutoff.
- **`status`.** `available`: the officials are served. `withheld`: officials exist but
  a source of them holds no display right for officials (`officials` empty; nothing about
  them is disclosed). Sportmonks holds the display right.
- **Freshness delay and billing** as for `GET /v1/fixtures/{id}/events`: a delayed grant
  is served what was known at `request time - delay`, and a response that is not
  `available` is recorded with 0 units.

Source references (`sources`, with `read:sources`) appear on an `available` response and
follow the source-reference rules for officials.

Parameters:
- `id` (path, string, required): Canonical or retired fixture identifier (`fx_<digits>`); another kind's prefix or an undecodable body is a 400 naming `id`.
- `known_at` (query, timestamp, optional): Knowledge cutoff (UTC); the answer reflects only what OddsFinder had recorded by this instant. Default is the request time. Must not be in the future.

Returns `200`: The fixture's officials as known at the cutoff.
The body is [the fixture officials object](obj-FixtureOfficials.md).

Errors: `400` Malformed parameter or cursor (`invalid-request`).; `401` Missing or invalid credential (`unauthenticated`).; `403` Operation not permitted (`forbidden`) or restricted by grants/rights (`not-entitled`).; `404` Unknown identifier at the requested cutoff (`not-found`).; `422` Well-formed but unanswerable (`invalid-range`, `unsupported-historical-capability`).; `429` The per-minute rate limit is used up (`rate-limited`) or a daily allowance is exhausted (`quota-exceeded`). Failed requests (403, 404, other 4xx, 5xx) use up the per-minute rate limit too.; `500` Unexpected failure (`internal-error`); `request_id` identifies the server-side record.; `503` A service this operation depends on, or the access check, is temporarily unavailable (`unavailable`, `policy-unavailable`).

Example request (200 · Withheld):

```bash
curl https://api.example.com/v1/fixtures/fx_1/officials \
  -H "X-API-Key: $ODDSFINDER_API_KEY"
```

Example response (200):

```json
{
  "fixture_id": "fx_1",
  "status": "withheld",
  "officials": [],
  "knowledge": {
    "known_at": "2026-10-03T16:00:00Z",
    "as_requested": false
  }
}
```