> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squadassist.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /query_player — Look Up a Player by ID

> Look up a player in SquadAssist using a Transfermarkt ID, Wyscout ID, or SquadAssist ID to retrieve their profile and internal player 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.

```http theme={null}
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.

<ParamField body="transfermarkt_id" type="integer">
  The player's Transfermarkt ID. Must be a positive integer no greater than 10^12.
</ParamField>

<ParamField body="wyscout_id" type="integer">
  The player's Wyscout ID. Must be a positive integer no greater than 10^12.
</ParamField>

<ParamField body="squadassist_id" type="string">
  The player's SquadAssist internal ID. If provided, it must be a valid SquadAssist ID string.
</ParamField>

<Note>
  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.
</Note>

## Response

<ResponseField name="squadassist_id" type="string">
  The SquadAssist internal player ID. Use this value in other API endpoints.
</ResponseField>

<ResponseField name="transfermarkt_id" type="integer | null">
  The player's Transfermarkt ID, or `null` if not linked.
</ResponseField>

<ResponseField name="wyscout_id" type="integer | null">
  The player's Wyscout ID, or `null` if not linked.
</ResponseField>

<ResponseField name="name" type="string">
  The player's full name as used in SquadAssist.
</ResponseField>

<ResponseField name="first_name" type="string">
  The player's first name.
</ResponseField>

<ResponseField name="last_name" type="string">
  The player's last name.
</ResponseField>

<ResponseField name="alias" type="string | null">
  An alternative name or nickname, if available. Otherwise `null`.
</ResponseField>

<ResponseField name="nationality" type="string">
  The player's nationality.
</ResponseField>

<ResponseField name="birth_date" type="string | null">
  The player's date of birth in `YYYY-MM-DD` format, or `null` if unavailable.
</ResponseField>

<ResponseField name="height" type="number | null">
  The player's height in centimetres, or `null` if unavailable.
</ResponseField>

<ResponseField name="preferred_foot" type="string | null">
  The player's preferred foot (e.g., `"Right"`, `"Left"`, `"Both"`), or `null` if unknown.
</ResponseField>

## 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

<CodeGroup>
  ```bash Powershell theme={null}
  $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
  ```

  ```python Python theme={null}
  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)
  ```

  ```r R theme={null}
  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)
  ```
</CodeGroup>

```json Response theme={null}
{
  "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"
}
```