Skip to main content
This guide walks you through the complete flow from a new account 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
  • The SquadAssist club ID for the club perspective you want to use in the ROI analysis
  • 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

1

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.At least one is required to use this guide, otherwise it is recommended to start from the POST /get_clubs_in_competition to retrieve all clubs in a competition and then all the players from each of these clubs. 
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.
2

Get the ROI analysis

POST /get_roi_analysis calculates a full three-component valuation (on-field value, marketing value, and projected transfer fee) 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"
  }'
FieldRequiredDescription
player_idYesSquadAssist player ID
club_idYesSquadAssist club ID for the valuation context
annual_wageNoPlayer’s annual gross wage, in currency_code
expected_transfer_valueNoYour estimated acquisition cost, in currency_code
currency_codeNoISO 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"
}

​
What’s next

  • POST /get_future_transfer_value — project the resale value of a player at end of contract
  • 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