Team Squad

Retrieve the complete squad roster for a specific team, including player details, positions, and staff.

GET /squads

Team Roster

cURL

curl --request GET \
  --url https://v1.basketball.sportsapipro.com/squads \
  --header 'x-api-key: <api-key>'

Overview

Returns the full squad information for a specified team (competitor), including all players, coaching staff, and position categories. This endpoint provides comprehensive athlete data such as age, jersey number, nationality, and formation positions.

User language, timezone, and country are automatically resolved by the upstream service. You can override timezoneName with a specific timezone (e.g., America/New_York). All date/time fields like birthdate use ISO 8601 format with a dynamic timezone offset.

Request Parameters

competitors · integer · required

The unique identifier of the team/competitor to retrieve squad for.

Example: 110 (Manchester City)

appTypeId · integer

Identifies the client application type.

Default: Automatically resolved

langId · integer

Language identifier for localized content.

Default: Automatically resolved

timezoneName · string

Timezone for date/time values (auto-resolved, or specify e.g., America/New_York). All date/time fields like birthdate use ISO 8601 format with a dynamic timezone offset.

Default: Automatically resolved

userCountryId · integer

Country identifier for regional content.

Default: Automatically resolved

Request Examples

cURL

curl -X GET "https://v1.football.sportsapipro.com/squads?competitors=110" \
  -H "x-api-key: YOUR_API_KEY"

Response Example

{
  "squads": [
    {
      "competitorId": 110,
      "athletes": [
        {
          "age": 25,
          "jerseyNum": 9,
          "birthdate": "2000-07-21T00:00:00+00:00",
          "gender": 1,
          "position": {
            "id": 4,
            "name": "Attacker"
          },
          "formationPosition": {
            "id": 12,
            "name": "Centre Forward",
            "order": 12
          },
          "height": 195,
          "id": 65760,
          "name": "Erling Haaland",
          "shortName": "Haaland",
          "nameForURL": "erling-haaland",
          "sportId": 1,
          "clubId": 110,
          "nationalityId": 27,
          "nationalTeamId": 2376,
          "imageVersion": 67
        },
        {
          "age": 54,
          "birthdate": "1971-01-18T00:00:00+00:00",
          "gender": 1,
          "position": {
            "id": 0
          },
          "formationPosition": {
            "id": 16,
            "name": "Coach",
            "order": 16
          },
          "height": 180,
          "id": 46115,
          "name": "Pep Guardiola",
          "shortName": "Guardiola",
          "nameForURL": "guardiola",
          "sportId": 1,
          "clubId": 110,
          "nationalityId": 2,
          "nationalTeamId": 5050,
          "imageVersion": 28
        }
      ],
      "positions": [
        {
          "id": 0,
          "name": "Management",
          "title": "Management",
          "isStaff": true
        },
        {
          "id": 1,
          "name": "Goalkeeper",
          "title": "Goalkeepers",
          "isStaff": false
        },
        {
          "id": 2,
          "name": "Defender",
          "title": "Defenders",
          "isStaff": false
        },
        {
          "id": 3,
          "name": "Midfielder",
          "title": "Midfielders",
          "isStaff": false
        },
        {
          "id": 4,
          "name": "Attacker",
          "title": "Attackers",
          "isStaff": false
        }
      ]
    }
  ],
  "sports": [...],
  "countries": [...],
  "competitions": [...],
  "competitors": [...]
}

Response Fields

Root Object

squads · array

Array of squad objects for the requested team(s).

sports · array

Array of sport definitions referenced in the response.

countries · array

Array of country definitions for player nationalities.

competitions · array

Array of competition definitions the team participates in.

competitors · array

Array of competitor/team definitions.

Squad Object

competitorId · integer

The unique identifier of the team this squad belongs to.

athletes · array

Array of athlete objects representing all squad members.

positions · array

Array of position category definitions used to group athletes.

Athlete Object

id · integer

Unique identifier for the athlete.

name · string

Full name of the athlete.

shortName · string

Abbreviated name for display purposes.

nameForURL · string

URL-friendly slug of the athlete’s name.

age · integer

Current age of the athlete in years.

jerseyNum · integer

Jersey/shirt number worn by the athlete. Not present for coaching staff.

birthdate · string

ISO 8601 formatted birth date with timezone.

gender · integer

Gender identifier (1 = Male, 2 = Female).

height · integer

Height of the athlete in centimeters.

position · object

Primary position category of the athlete.

Show Position properties

id · integer

Position category ID (0=Management, 1=Goalkeeper, 2=Defender, 3=Midfielder, 4=Attacker).

name · string

Display name of the position category.

formationPosition · object

Specific formation position of the athlete.

Show Formation position properties

id · integer

Formation position ID.

name · string

Display name (e.g., “Centre Forward”, “Left Back”, “Coach”).

order · integer

Display order for sorting positions.

sportId · integer

Sport identifier (1 = Football).

clubId · integer

Current club/team identifier.

nationalityId · integer

Country ID representing the athlete’s nationality.

nationalTeamId · integer

National team ID if the athlete represents a national team.

imageVersion · integer

Version number for athlete image caching.

createdAt · string

ISO 8601 timestamp when the athlete record was created.

Position Category Object

id · integer

Unique identifier for the position category.

name · string

Short name of the position (e.g., “Goalkeeper”, “Defender”).

title · string

Plural display title for grouping (e.g., “Goalkeepers”, “Defenders”).

isStaff · boolean

Whether this category represents non-playing staff (coaches, managers).

Position Categories

ID	Name	Title	Is Staff
0	Management	Management	Yes
1	Goalkeeper	Goalkeepers	No
2	Defender	Defenders	No
3	Midfielder	Midfielders	No
4	Attacker	Attackers	No

Formation Positions

ID	Name	Order
1	Goalkeeper	1
3	Left Back	3
4	Defensive Midfield	4
5	Centre Back	5
6	Right Back	6
8	Central Midfield	8
9	Attacking Midfield	9
11	Left Forward	11
12	Centre Forward	12
14	Right Forward	14
16	Coach	16

Notes

• The squad includes both players and coaching staff
• Coaching staff members (position ID 0) do not have jersey numbers
• Athletes may have both position (category) and formationPosition (specific role)
• The positions array provides category definitions for grouping athletes in the UI
• Use imageVersion when constructing athlete image URLs for cache busting

Authorizations

x-api-key · string · header · required

Your SportsAPI Pro API key

Query Parameters

competitors · integer · required

Team/Competitor ID

Example:

2827

Response

200

Team roster retrieved successfully