API reference

Squads

Copy as Markdown

# Squads

## Retrieve fixture squads

`GET /v1/fixtures/{fixture_id}/squads`

Get eligible player IDs, names and positions for both sides at zero credits, plus supported formations. Start probabilities and expected selections belong to [Opono Expected Lineup](/docs/reference/expected-lineup).

Authentication: Bearer API key with `data.read`; active Plus or Pro plan required.

### Parameters

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fixture_id` | integer | Yes | Use a returned fixture ID instead of home, away, and date; minimum: 1. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | None. |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | None. |

### Example request

```bash
curl 'https://api.opono.com/v1/fixtures/19609874/squads' \
  --header "Authorization: Bearer $OPONO_API_KEY"
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | fixture_squads. |
| `fixture_id` | integer | Selected fixture. |
| `squad_version` | string | Squad identity echoed as inputs.squad_version on quotes and runs. |
| `data_version` | string | Current fixture input version. |
| `as_of` | string | Input watermark in ISO 8601 UTC. |
| `lineups_announced` | boolean | Whether official team sheets are published. |
| `formations` | array | Accepted formation strings for custom lineups. |
| `home / away` | object | Each side's team and players. |
| `home.team / away.team` | object | Team ID and name. |
| `home.players / away.players` | array | Eligible players for this side. |
| `home.players[].player_id` | integer | Player ID to use in xi or bench; the same fields apply to away. |
| `home.players[].name` | string | Player label. |
| `home.players[].position` | string or null | goalkeeper, defender, midfielder, attacker, or null when unlabelled. |
| `freshness` | object | Fixture freshness when present; unavailable or refreshing squads return an error. |

### Example response

200 synthetic test response; every player entry has only player_id, name and position.

```json
{
  "object": "fixture_squads",
  "fixture_id": 19609874,
  "squad_version": "sq1:example",
  "data_version": "example-input-version",
  "as_of": "2026-10-17T09:00:00Z",
  "lineups_announced": false,
  "formations": [
    "4-3-3"
  ],
  "home": {
    "team": {
      "team_id": 1,
      "name": "Home"
    },
    "players": [
      {
        "player_id": 101,
        "name": "Home player 1",
        "position": "goalkeeper"
      },
      {
        "player_id": 102,
        "name": "Home player 2",
        "position": "defender"
      },
      {
        "player_id": 103,
        "name": "Home player 3",
        "position": "defender"
      },
      {
        "player_id": 104,
        "name": "Home player 4",
        "position": "defender"
      },
      {
        "player_id": 105,
        "name": "Home player 5",
        "position": "defender"
      },
      {
        "player_id": 106,
        "name": "Home player 6",
        "position": "midfielder"
      },
      {
        "player_id": 107,
        "name": "Home player 7",
        "position": "midfielder"
      },
      {
        "player_id": 108,
        "name": "Home player 8",
        "position": "midfielder"
      },
      {
        "player_id": 109,
        "name": "Home player 9",
        "position": "attacker"
      },
      {
        "player_id": 110,
        "name": "Home player 10",
        "position": "attacker"
      },
      {
        "player_id": 111,
        "name": "Home player 11",
        "position": "attacker"
      }
    ]
  },
  "away": {
    "team": {
      "team_id": 2,
      "name": "Away"
    },
    "players": [
      {
        "player_id": 201,
        "name": "Away player 1",
        "position": "goalkeeper"
      },
      {
        "player_id": 202,
        "name": "Away player 2",
        "position": "defender"
      },
      {
        "player_id": 203,
        "name": "Away player 3",
        "position": "defender"
      },
      {
        "player_id": 204,
        "name": "Away player 4",
        "position": "defender"
      },
      {
        "player_id": 205,
        "name": "Away player 5",
        "position": "defender"
      },
      {
        "player_id": 206,
        "name": "Away player 6",
        "position": "midfielder"
      },
      {
        "player_id": 207,
        "name": "Away player 7",
        "position": "midfielder"
      },
      {
        "player_id": 208,
        "name": "Away player 8",
        "position": "midfielder"
      },
      {
        "player_id": 209,
        "name": "Away player 9",
        "position": "attacker"
      },
      {
        "player_id": 210,
        "name": "Away player 10",
        "position": "attacker"
      },
      {
        "player_id": 211,
        "name": "Away player 11",
        "position": "attacker"
      }
    ]
  }
}
```

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `parameter_invalid` | A parameter has an invalid value. |
| 401 | `invalid_api_key` | The credential cannot authenticate. |
| 401 | `key_revoked` | The API key has been revoked. |
| 401 | `key_expired` | The API key has expired. |
| 403 | `scope_missing` | The key lacks the required scope. |
| 403 | `tier_restricted` | The organisation plan does not include this operation. |
| 403 | `org_suspended` | Your account is suspended. |
| 403 | `ip_not_allowed` | The caller is outside the key's IP allowlist. |
| 429 | `rate_limited` | A request or authentication rate limit was exceeded. |
| 503 | `dependency_unavailable` | Request admission is unavailable. |
| 503 | `maintenance` | The API is paused for maintenance. |
| 404 | `fixture_not_found` | No matching simulation fixture exists. |
| 400 | `fixture_not_covered` | The requested fixture is not available for simulation. |
| 503 | `refreshing` | The request can't be checked right now. |

Retrieve fixture squads

GET /v1/fixtures/{fixture_id}/squads

Get eligible player IDs, names and positions for both sides at zero credits, plus supported formations. Start probabilities and expected selections belong to Opono Expected Lineup.

Authentication: Bearer API key with data.read; active Plus or Pro plan required.

Parameters

Path parameters

Name	Type	Required	Description
`fixture_id`	integer	Yes	Use a returned fixture ID instead of home, away, and date; minimum: 1.

Query parameters

Name	Type	Required	Description
—	—	—	None.

Body parameters

Name	Type	Required	Description
—	—	—	None.

Example request

bash

curl 'https://api.opono.com/v1/fixtures/19609874/squads' \
  --header "Authorization: Bearer $OPONO_API_KEY"

Response

Field	Type	Description
`object`	string	fixture_squads.
`fixture_id`	integer	Selected fixture.
`squad_version`	string	Squad identity echoed as inputs.squad_version on quotes and runs.
`data_version`	string	Current fixture input version.
`as_of`	string	Input watermark in ISO 8601 UTC.
`lineups_announced`	boolean	Whether official team sheets are published.
`formations`	array	Accepted formation strings for custom lineups.
`home / away`	object	Each side's team and players.
`home.team / away.team`	object	Team ID and name.
`home.players / away.players`	array	Eligible players for this side.
`home.players[].player_id`	integer	Player ID to use in xi or bench; the same fields apply to away.
`home.players[].name`	string	Player label.
`home.players[].position`	string or null	goalkeeper, defender, midfielder, attacker, or null when unlabelled.
`freshness`	object	Fixture freshness when present; unavailable or refreshing squads return an error.

Example response

200 synthetic test response; every player entry has only player_id, name and position.

json

{
  "object": "fixture_squads",
  "fixture_id": 19609874,
  "squad_version": "sq1:example",
  "data_version": "example-input-version",
  "as_of": "2026-10-17T09:00:00Z",
  "lineups_announced": false,
  "formations": [
    "4-3-3"
  ],
  "home": {
    "team": {
      "team_id": 1,
      "name": "Home"
    },
    "players": [
      {
        "player_id": 101,
        "name": "Home player 1",
        "position": "goalkeeper"
      },
      {
        "player_id": 102,
        "name": "Home player 2",
        "position": "defender"
      },
      {
        "player_id": 103,
        "name": "Home player 3",
        "position": "defender"
      },
      {
        "player_id": 104,
        "name": "Home player 4",
        "position": "defender"
      },
      {
        "player_id": 105,
        "name": "Home player 5",
        "position": "defender"
      },
      {
        "player_id": 106,
        "name": "Home player 6",
        "position": "midfielder"
      },
      {
        "player_id": 107,
        "name": "Home player 7",
        "position": "midfielder"
      },
      {
        "player_id": 108,
        "name": "Home player 8",
        "position": "midfielder"
      },
      {
        "player_id": 109,
        "name": "Home player 9",
        "position": "attacker"
      },
      {
        "player_id": 110,
        "name": "Home player 10",
        "position": "attacker"
      },
      {
        "player_id": 111,
        "name": "Home player 11",
        "position": "attacker"
      }
    ]
  },
  "away": {
    "team": {
      "team_id": 2,
      "name": "Away"
    },
    "players": [
      {
        "player_id": 201,
        "name": "Away player 1",
        "position": "goalkeeper"
      },
      {
        "player_id": 202,
        "name": "Away player 2",
        "position": "defender"
      },
      {
        "player_id": 203,
        "name": "Away player 3",
        "position": "defender"
      },
      {
        "player_id": 204,
        "name": "Away player 4",
        "position": "defender"
      },
      {
        "player_id": 205,
        "name": "Away player 5",
        "position": "defender"
      },
      {
        "player_id": 206,
        "name": "Away player 6",
        "position": "midfielder"
      },
      {
        "player_id": 207,
        "name": "Away player 7",
        "position": "midfielder"
      },
      {
        "player_id": 208,
        "name": "Away player 8",
        "position": "midfielder"
      },
      {
        "player_id": 209,
        "name": "Away player 9",
        "position": "attacker"
      },
      {
        "player_id": 210,
        "name": "Away player 10",
        "position": "attacker"
      },
      {
        "player_id": 211,
        "name": "Away player 11",
        "position": "attacker"
      }
    ]
  }
}

Errors

Status	Code	Meaning
400	`parameter_invalid`	A parameter has an invalid value.
401	`invalid_api_key`	The credential cannot authenticate.
401	`key_revoked`	The API key has been revoked.
401	`key_expired`	The API key has expired.
403	`scope_missing`	The key lacks the required scope.
403	`tier_restricted`	The organisation plan does not include this operation.
403	`org_suspended`	Your account is suspended.
403	`ip_not_allowed`	The caller is outside the key's IP allowlist.
429	`rate_limited`	A request or authentication rate limit was exceeded.
503	`dependency_unavailable`	Request admission is unavailable.
503	`maintenance`	The API is paused for maintenance.
404	`fixture_not_found`	No matching simulation fixture exists.
400	`fixture_not_covered`	The requested fixture is not available for simulation.
503	`refreshing`	The request can't be checked right now.