From public IDs to ROI analysis

This guide walks you through the complete flow from a public ID (e.g., Transfermarkt or Wyscout ID) to a working API response. By the end you will have authenticated, resolved a player ID, and retrieved a full valuation for that player at a specific club.

Prerequisites

Before you start, make sure you have:

A SquadAssist account with an API key
A SquadAssist player ID, Transfermarkt player ID, or Wyscout player ID for the player you want to evaluate (at least one is needed, otherwise see
The SquadAssist club ID for the club perspective you want to use in the ROI analysis. This is typically your own club.
curl available in your terminal (all examples below use curl)

Player IDs and club IDs are drawn from the SquadAssist database. Use POST /query_player and POST /query_club to resolve external IDs (Transfermarkt, Wyscout) to SquadAssist IDs before calling valuation endpoints.

Step-by-step

Look up a player

Use POST /query_player to resolve a player’s external IDs and confirm they exist in the SquadAssist database. You can supply any combination of squadassist_id, transfermarkt_id, or wyscout_id.

curl -X POST https://api.squadassist.ai/v1/query_player \
  -H "x-api-key: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transfermarkt_id": 123456
  }'

The response gives you the player’s SquadAssist ID and profile fields:

{
  "squadassist_id": "P01JJ...",
  "transfermarkt_id": 123456,
  "wyscout_id": 789012,
  "name": "Jan De Smedt",
  "first_name": "Jan",
  "last_name": "De Smedt",
  "alias": null,
  "nationality": "BEL",
  "birth_date": "1998-03-15",
  "height": 182,
  "preferred_foot": "right"
}

Note the squadassist_id from this response—you will need it for valuation calls.

Get the ROI analysis

POST /roi_analysis calculates a full value creation estimation (sportive impact and future transfer value) for a player at a specific club. The player_id and club_id fields are required; wage and expected transfer value are optional inputs that affect the financial return calculation.

curl -X POST https://api.squadassist.ai/v1/get_roi_analysis \
  -H "x-api-key: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "player_id": "P01JJ...",
    "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
    "annual_wage": 1500000,
    "expected_transfer_value": 8000000,
    "currency_code": "EUR"
  }'

Field	Required	Description
`player_id`	Yes	SquadAssist player ID
`club_id`	Yes	SquadAssist club ID for the valuation context
`annual_wage`	No	Player’s annual gross wage, in `currency_code`
`expected_transfer_value`	No	Your estimated acquisition cost, in `currency_code`
`currency_code`	No	ISO 4217 code for input amounts (defaults to `EUR`)

The response contains the full valuation breakdown. All monetary values are returned in the currency you specified via currency_code.

{
  "currency": "EUR",
  "total_value": 12400000,
  "on_field_value": 6200000,
  "marketing_value": 950000,
  "future_transfer_value": 7800000,
  "roi": 1.55,
  "simulation_years": 3,
  "player_id": "P01JJ...",
  "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8"
}

End-to-end python code

import time
import requests

BASE_URL = "https://api.squadassist.ai/v1"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}
IDS_TO_process = [982081, 733410, 981398, 565431, 409490, 1053160, 919173, 847279, 745178, 1086381, 183383, 950874, 1233680, 1120020, 1208836, 993333, 679050, 1451916, 583913, 668587, 923838, 1176433, 579089, 1105918, 1021007, 1467501, 110822, 1474022, 1464975, 1451913, 477460] #Adjust appropriately 

def post_with_retry(endpoint, payload, max_retries=3):
url = f"{BASE_URL}/{endpoint}"
for attempt in range(max_retries):
    resp = requests.post(url, headers=HEADERS, json=payload)
    if resp.status_code == 429:
        wait = resp.json().get("retry_after_seconds", 10)
        print(f"Rate limited. Waiting {wait}s...")
        time.sleep(wait)
        continue
    if resp.status_code == 403:
        #Some players are available but not yet ready for ROI analysis. We will translate that error here so it's easier to access in the try except below 
        if resp.json().get("error") == "This player_is not available for analysis":
            raise AttributeError("Player can't be analysed yet")
    resp.raise_for_status()
    return resp.json()
raise Exception("Rate limit retries exhausted")

for id in IDS_TO_process:
# Step 1 — Resolve player via Transfermarkt ID
player = post_with_retry("query_player", {"transfermarkt_id": id}) #Adjust to other ID type if needed
print("Player:", player["name"], "| ID:", player["squadassist_id"])

# Step 2 — Get ROI analysis
try: 
    roi = post_with_retry("get_roi_analysis", {
        "player_id": player["squadassist_id"],
        "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
        "annual_wage": 1500000,
        "expected_transfer_value": 8000000,
        "currency_code": "EUR",
    })
    print("ROI Analysis for", player["name"])
    print("Total value:", roi["total_value_created"])
    print("ROI:", roi["return_on_investment"])
except AttributeError as e:
    print(f"Skipping {player['name']} as he can't be analysed yet: {e}")
except Exception as e:
    print(f"Error processing {player['name']}: {e}")

What’s next

POST /get_future_transfer_value — project the resale value of a player in 3 years
GET /expected_transfer_value — get the current expected transfer fee for a player
GET /player_info — retrieve detailed position, role, and club affiliation data for a player

​Prerequisites

​Step-by-step

​End-to-end python code

​What’s next

Prerequisites

Step-by-step

End-to-end python code

What’s next