Skip to main content
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.
​
transfermarkt_id
integer
The player’s Transfermarkt ID. Must be a positive integer no greater than 10^12.
​
wyscout_id
integer
The player’s Wyscout ID. Must be a positive integer no greater than 10^12.
​
squadassist_id
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

​
squadassist_id
string
The SquadAssist internal player ID. Use this value in other API endpoints.
​
transfermarkt_id
integer | null
The player’s Transfermarkt ID, or null if not linked.
​
wyscout_id
integer | null
The player’s Wyscout ID, or null if not linked.
​
name
string
The player’s full name as used in SquadAssist.
​
first_name
string
The player’s first name.
​
last_name
string
The player’s last name.
​
alias
string | null
An alternative name or nickname, if available. Otherwise null.
​
nationality
string
The player’s nationality.
​
birth_date
string | null
The player’s date of birth in YYYY-MM-DD format, or null if unavailable.
​
height
number | null
The player’s height in centimetres, or null if unavailable.
​
preferred_foot
string | null
The player’s preferred foot (e.g., "Right", "Left", "Both"), or null if unknown.

​
Errors

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

​
Example

curl -s -X POST https://api.squadassist.ai/v1/query_player \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transfermarkt_id": 28003}'
Response
{
  "squadassist_id": "P01JJBVJAPKG8CM7ZA5JF5G84R8",
  "transfermarkt_id": 28003,
  "wyscout_id": 123456,
  "name": "Lior Refaelov",
  "first_name": "Lior",
  "last_name": "Refaelov",
  "alias": null,
  "nationality": "Israel",
  "birth_date": "1986-04-26",
  "height": 175,
  "preferred_foot": "Right"
}