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

# Get full ROI analysis for a player signing

> Calculate the full ROI for signing a player: on-field value, future transfer fee, and cost over a 3-year period combined into a single ratio.

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.

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

## Request

The request body must be a JSON object.

<ParamField body="player_id" type="string" required>
  The SquadAssist player ID. Use `POST /query_player` to look up the ID.
</ParamField>

<ParamField body="club_id" type="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.
</ParamField>

<ParamField body="annual_wage" type="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.
</ParamField>

<ParamField body="expected_transfer_value" type="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.
</ParamField>

<ParamField body="currency_code" type="string">
  An [ISO 4217](https://en.wikipedia.org/wiki/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`.
</ParamField>

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

<ResponseField name="currency" type="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.
</ResponseField>

<ResponseField name="expected_transfer_value" type="integer">
  The transfer fee used in the calculation, in the requested currency.
</ResponseField>

<ResponseField name="expected_transfer_value_in_eur" type="integer">
  The transfer fee used in the calculation, in EUR.
</ResponseField>

<ResponseField name="annual_wage" type="integer or null">
  The annual wage used in the calculation, in the requested currency. `null` if no wage was provided.
</ResponseField>

<ResponseField name="annual_wage_in_eur" type="integer or null">
  The annual wage used in the calculation, in EUR. `null` if no wage was provided.
</ResponseField>

<ResponseField name="total_value_created" type="integer">
  The total projected value created by the player over the 3-year simulation period (sportive impact + future transfer value), in the requested currency.
</ResponseField>

<ResponseField name="total_value_created_in_eur" type="integer">
  The total projected value created, in EUR.
</ResponseField>

<ResponseField name="return_on_investment" type="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.
</ResponseField>

<ResponseField name="sportive_impact" type="object">
  The on-field (eLPAR) component of the analysis. See [POST /get\_sportive\_impact](/api-reference/valuation/sportive-impact) for the structure of this object.
</ResponseField>

<ResponseField name="future_transfer_value" type="object">
  The future transfer fee prediction component. See [POST /get\_future\_transfer\_value](/api-reference/valuation/future-transfer-value) for the structure of this object.
</ResponseField>

<ResponseField name="player_info" type="object">
  A summary of the player's current attributes used in the analysis.

  <Expandable title="player_info fields">
    <ResponseField name="age" type="integer">
      Player age at the time of analysis.
    </ResponseField>

    <ResponseField name="position" type="string">
      Player's primary position.
    </ResponseField>

    <ResponseField name="best_role" type="string">
      The SquadAssist role the player is best suited to.
    </ResponseField>

    <ResponseField name="current_rating" type="integer">
      The player's current ability rating.
    </ResponseField>

    <ResponseField name="current_potential" type="integer">
      The player's potential ability rating.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

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

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

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

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