Get full ROI analysis for a player signing

The POST /get_roi_analysis endpoint calculates the full return on investment (ROI) for signing a player to a specific club. It runs a 3-year simulation that combines three components: the player’s sportive (on-field) impact expressed in monetary terms, a prediction of their future transfer fee based on comparable historical players, and the total cost of signing (transfer fee plus wages). The result includes each component broken down individually, the overall ROI ratio, and the similar historical players used for the future transfer value prediction.

The analysis is always run against the 2025/2026 season. Season is not yet a request parameter. The club_id must be club inside your coverage. Contact SquadAssist to adjust access.

Request

The request body must be a JSON object.

string

required

The SquadAssist player ID. Use POST /query_player to look up the ID.

string

required

The SquadAssist club ID for the signing club. Contact SquadAssist to confirm which club IDs are available on your plan. Use POST /query_club to look up the ID.

number

The player’s annual wage in the currency specified by currency_code. If omitted, wage is treated as zero and no wage cost is included in the ROI calculation — the response will note this in the result.

number

The transfer fee you expect to pay, in the currency specified by currency_code. If omitted, SquadAssist’s model calculates an expected fee automatically based on the player’s profile and the signing club.

string

An ISO 4217 currency code (e.g. EUR, GBP, USD). All input amounts (annual_wage, expected_transfer_value) are interpreted in this currency. Defaults to EUR.

Response

The response is a JSON object containing each component of the ROI analysis. All monetary values are provided in both the requested currency and EUR.

string

The ISO 4217 currency code used for all non-EUR monetary values in the response. Matches your currency_code input, or EUR if none was provided.

integer

The transfer fee used in the calculation, in the requested currency.

integer

The transfer fee used in the calculation, in EUR.

integer or null

The annual wage used in the calculation, in the requested currency. null if no wage was provided.

integer or null

The annual wage used in the calculation, in EUR. null if no wage was provided.

integer

The total projected value created by the player over the 3-year simulation period (sportive impact + future transfer value), in the requested currency.

integer

The total projected value created, in EUR.

number or null

The ROI ratio: total_value_created / (transfer_fee + annual_wage * 3). A value above 1.0 means the player is projected to create more value than they cost. null when total cost is zero.

object

The on-field (eLPAR) component of the analysis. See POST /get_sportive_impact for the structure of this object.

object

The future transfer fee prediction component. See POST /get_future_transfer_value for the structure of this object.

object

A summary of the player’s current attributes used in the analysis.

Show player_info fields

integer

Player age at the time of analysis.

string

Player’s primary position.

string

The SquadAssist role the player is best suited to.

integer

The player’s current ability rating.

integer

The player’s potential ability rating.

Example

$headers = @{
    "x-api-key"    = "your API key" # Change
    "Content-Type" = "application/json"
}

$body = @{
    "player_id"               = "P01K0WPQJPWZCNCYH1KXHTJ9R31" #Change ID to desired player
    "club_id"                 = "C01JJBVJAPKG8CM7ZA5JF5G84R8" #Change ID to desired buying club
    "expected_transfer_value" = 4000000
	"annual_wage" 			  = 120000
    "currency_code"           = "EUR"
}

Invoke-RestMethod -Uri "https://api.squadassist.ai/v1/get_roi_analysis" `
                  -Method Post `
                  -Headers $headers `
                  -Body ($body | ConvertTo-Json)

import requests

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

# 2. Set up your headers
headers = {
    "x-api-key": "your_API_key",  # Replace with your actual key
    "Content-Type": "application/json"
}

# 3. Define the data (equivalent to the PowerShell $body)
payload = {
    "player_id": "P01K0WPQJPWZCNCYH1KXHTJ9R31",
    "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
    "expected_transfer_value": 4000000,
	"annual_wage": 120000,
    "currency_code": "EUR"
}

# 4. Make the POST request
response = requests.post(url, headers=headers, json=payload)

# 5. Output the result
if response.status_code == 200:
    data = response.json()
    print("Success!")
    print(data)
else:
    print(f"Error {response.status_code}: {response.text}")

{
  "currency": "EUR",
  "expected_transfer_value": 4000000,
  "expected_transfer_value_in_eur": 4000000,
  "annual_wage": 1200000,
  "annual_wage_in_eur": 1200000,
  "total_value_created": 12500000,
  "total_value_created_in_eur": 12500000,
  "return_on_investment": 1.79,
  "sportive_impact": {
    "currency": "EUR",
    "on_field_value": 6800000,
    "on_field_value_in_eur": 6800000,
    "simulation": {
      "increase_in_expected_position": 2,
      "new_expected_position": 4.1,
      "original_expected_position": 6.1
    },
    "playing_time_percentage": 0.72
  },
  "future_transfer_value": {
    "currency": "EUR",
    "future_transfer_value": 5700000,
    "future_transfer_value_in_eur": 5700000,
    "value_category": "Steady Grower",
    "explanations": {
      "simulation_years": 3,
      "over_thirthy_years": false,
      "similar_players": [
        {
          "name": "Example Player",
          "initial_value": 3800000,
          "initial_rating": 67,
          "initial_potential": 72,
          "later_transfer_value": 5500000,
          "age": 24,
          "season": "2021/2022",
          "position": "CM",
          "best_role": "Box-to-box midfielder"
        }
      ]
    },
    "probabilities_of_different_outcomes": {
      "probabilities": {
        "Elite Prospect": 0.05,
        "Excellent Opportunity": 0.12,
        "Steady Grower": 0.41,
        "Stable Value": 0.28,
        "Decline": 0.10,
        "Major decline": 0.04
      },
      "sample_size": 30
    }
  },
  "player_info": {
    "age": 25,
    "position": "CM",
    "best_role": "Box-to-box midfielder",
    "current_rating": 68,
    "current_potential": 73
  }
}

Errors

Status	Body	Cause
`400`	`{"error": "player_id is required"}`	`player_id` was not included in the request body
`400`	`{"error": "club_id is required"}`	`club_id` was not included in the request body
`400`	`{"error": "Invalid player_id"}`	The `player_id` format is not valid
`400`	`{"error": "Invalid club_id"}`	The `club_id` format is not valid
`400`	`{"error": "currency_code must be a string"}`	`currency_code` was provided but is not a string
`400`	`{"error": "<message>"}`	The `currency_code` is not a valid ISO 4217 code
`403`	`{"error": "Player is not in the allowed leagues"}`	The player is not in your current coverage
`403`	`{"error": "Requested club is not allowed"}`	The `club_id` is not available on your plan
`404`	`{"error": "Club not found"}`	No club was found for the provided `club_id`

Overview

Players

Clubs

Competitions

Predictions

Get full ROI analysis for a player signing

Request

Response

Example

Errors

​Request

​Response

​Example

​Errors

Request

Response

Example

Errors