POST /query_player — Look Up a Player by ID

Use this endpoint to look up a player’s SquadAssist record using one or more external identifiers. Submit at least one of transfermarkt_id, wyscout_id, or squadassist_id in the request body. The response returns the player’s SquadAssist ID alongside basic profile data, which you can then pass to other endpoints such as GET /player_info.

Authentication

All requests must include a valid API key, either as an x-api-key header or as a Bearer token in the Authorization header.

x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY

Request

The request body must be a JSON object containing at least one of the following fields.

integer

The player’s Transfermarkt ID. Must be a positive integer no greater than 10^12.

integer

The player’s Wyscout ID. Must be a positive integer no greater than 10^12.

string

The player’s SquadAssist internal ID. If provided, it must be a valid SquadAssist ID string.

At least one of transfermarkt_id, wyscout_id, or squadassist_id must be present in the request body. Requests that omit all three fields return a 400 error.

Response

string

The SquadAssist internal player ID. Use this value in other API endpoints.

integer | null

The player’s Transfermarkt ID, or null if not linked.

integer | null

The player’s Wyscout ID, or null if not linked.

string

The player’s full name as used in SquadAssist.

string

The player’s first name.

string

The player’s last name.

string | null

An alternative name or nickname, if available. Otherwise null.

string

The player’s nationality.

string | null

The player’s date of birth in YYYY-MM-DD format, or null if unavailable.

number | null

The player’s height in centimetres, or null if unavailable.

string | null

The player’s preferred foot (e.g., "Right", "Left", "Both"), or null if unknown.

Errors

Status	Description
`400`	Invalid ID format, all ID fields omitted, or request body is not a JSON object.
`403`	Player exists but is not yet ready or is not accessible under your account.
`404`	No player found matching the supplied IDs.

Example

$headers = @{
    "x-api-key"    = "your API key" # Change
    "Content-Type" = "application/json"
}

Invoke-RestMethod -Uri "https://api.squadassist.ai/v1/query_player" `
                  -Method Post `
                  -Headers $headers `
                  -Body '{"transfermarkt_id": 28003}' #Change ID to desired player

import requests
import json

# 1. Define the endpoint
url = "https://api.squadassist.ai/v1/query_player"

# 2. Set up your headers 
headers = {
    "x-api-key": "your API key", #Change
    "Content-Type": "application/json"
}

# 3. Define the data you want to send
payload = {
    "transfermarkt_id": 28003 #Change to the relevant player
}

# 4. Make the POST request
response = requests.post(url, headers=headers, json=payload)

# 5. Handle the response
if response.status_code == 200:
    player_data = response.json()
    print("Success!")
    print(player_data)
else:
    print(f"Failed with status code: {response.status_code}")
    print(response.text)

library(httr2)

# 1. Define the base request
req <- httr2::request("https://api.squadassist.ai/v1/query_player") |>
  httr2::req_headers(
    "x-api-key" = "your API key", #Change
    "Content-Type" = "application/json"
  ) |>
  # 2. Add the JSON body
  httr2::req_body_json(list(transfermarkt_id = 28003))

# 3. Perform the request
resp <- httr2::req_perform(req)

# 4. Parse the data
player_data <- httr2::resp_body_json(resp)
print(player_data)

Response

{
  "squadassist_id": "P01JJ9Q3GF9J3GPK1R26QDW52V5",
  "transfermarkt_id": 28003,
  "wyscout_id": 3359,
  "name": "Lionel Messi",
  "first_name": "Lionel",
  "last_name": "Messi",
  "alias": "L. Messi",
  "nationality": "Argentina",
  "birth_date": "1987-06-24",
  "height": 169,
  "preferred_foot": "Left"
}

Overview

Players

Clubs

Competitions

Predictions

POST /query_player — Look Up a Player by ID

Authentication

Request

Response

Errors

Example

​Authentication

​Request

​Response

​Errors

​Example

Authentication

Request

Response

Errors

Example