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

# Look up a club by Transfermarkt or SquadAssist ID

> Resolve a club's SquadAssist ID and details using a Transfermarkt club ID or an existing SquadAssist club ID. At least one identifier is required.

The `POST /query_club` endpoint looks up a club in the SquadAssist database using an external or internal ID. Use it to resolve the `club_id` required by the valuation endpoints when you only have a Transfermarkt ID. The response returns the club's SquadAssist ID, Transfermarkt ID, and the club's name.

## Request

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

<ParamField body="transfermarkt_id" type="integer">
  The Transfermarkt club ID (a positive integer). You can find this in the Transfermarkt URL for a club — for example, `rsca.be` has the Transfermarkt ID `415`.
</ParamField>

<ParamField body="squadassist_id" type="string">
  A SquadAssist internal club ID. Use this to verify or enrich a club ID you already have.
</ParamField>

## Response

<ResponseField name="squadassist_id" type="string">
  The SquadAssist internal club ID. Pass this as `club_id` in the valuation endpoints.
</ResponseField>

<ResponseField name="transfermarkt_id" type="integer or null">
  The Transfermarkt club ID associated with this club. `null` if no Transfermarkt ID is recorded.
</ResponseField>

<ResponseField name="name" type="string">
  The club's name as it appears in SquadAssist.
</ResponseField>

## 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_club" `
                    -Method Post `
                    -Headers $headers `
                    -Body '{"transfermarkt_id": 520}' #Change ID to desired club
  ```

  ```python Python theme={null}
  import requests
  import json

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

  # 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": 520 #Change to the relevant club
  }

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

  ```text R theme={null}
  library(httr2)

  # 1. Define the base request
  req <- httr2::request("https://api.squadassist.ai/v1/query_club") |>
    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 = 520))

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

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

<ResponseExample>
  ```json Response theme={null}
  {
    "squadassist_id": "C01JJBSWKE71ZEN2E52257YQGP5",
    "transfermarkt_id": 520,
    "name": "Cercle Brugge"
  }
  ```
</ResponseExample>

## Errors

| Status | Body                                                                               | Cause                                                                 |
| ------ | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `400`  | `{"error": "At least one of transfermarkt_id or squadassist_id must be provided"}` | The request body contained neither identifier                         |
| `400`  | `{"error": "transfermarkt_id must be an integer"}`                                 | `transfermarkt_id` was provided but could not be parsed as an integer |
| `400`  | `{"error": "transfermarkt_id must be a positive integer"}`                         | `transfermarkt_id` was zero or negative                               |
| `400`  | `{"error": "transfermarkt_id is out of allowed range"}`                            | `transfermarkt_id` exceeded the maximum allowed value                 |
| `400`  | `{"error": "Invalid squadassist_id"}`                                              | The `squadassist_id` format is not valid                              |
| `404`  | `{"error": "Club not found"}`                                                      | No club matched the provided identifier(s)                            |