# API reference

**Overview**

Whenever the Assetario API is invoked, it provides a singular response output. The possible replies include either a prediction, an error message, or a null value.

#### Integration Options

Partners can choose one of the two methods to implement the Assetario API:

1. **Directly from the end-user device**: This is the recommended method.
2. **Via the customer’s backend service**: In this scenario, ensure that the `clientIp` field is populated.

All `customFields` to be passed in the body of the API call must be agreed upon during the integration process.

#### Endpoint Details

* **Base URL**: `https://prediction.api.assetario.com/predict`
* **Consumes**: `application/json`
* **Produces**: `application/json`

#### Sample API Request

To request a country pricing prediction, use the following cURL command:

```bash
curl -X 'POST' 'https://prediction.api.assetario.com/predict/{"auth_token"}' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    # --- MANDATORY FIELDS ---
    "userId": "2345",
    "predictionType": "pricing_tier",
    "deviceMake": "apple",
    "deviceModel": "iphone9,3",
    "devicePlatformName": "iOS",
    "devicePlatformVersion": "14",
    "deviceFamily": "phone", 
    "deviceLanguage": "eng",
    "appVersion": "5.6.1",
    "clientIp": "192.168.100.1"
}'
```

{% hint style="danger" %}
**Note**: Ensure that the format for **`deviceModel`** and **`deviceMake`** matches the structure found in the data dump. For instance, if Appsflyer is being used for collecting device info, use Appsflyer’s format in the API request as well.
{% endhint %}

{% hint style="danger" %}
**Note**: Ensure that you **call the API for both the Control and Personalized groups**, and discard the predictions for the Control group. We are using these prediction calls as an additional parameter for analytics and model training.
{% endhint %}

#### API Responses

**1. Correct Response**

The expected response when the API call is successful:

```json
{
  "prediction": {
    "predictionType": "price_multiplier",
    "userId": "2345",
    "predictedValue": "200",
    "abTestGroup": "personalized"
  }
}
```

**2. Missing Mandatory Attribute**

In case a mandatory attribute is missing from the request (only the first missing attribute is mentioned):

```json
{
  "error": {
    "code": "missing-data",
    "message": "Missing input data, path: \"deviceModel\""
  }
}
```

#### 3. Null Group Response

In case you receive a `null` response, please use the baseline price / treat the user as if they were in the control group:

```json
{
  "prediction": {
    "predictionType": "starter_pack",
    "userId": "2345",
    "predictedValue": "null",
    "abTestGroup": "personalized"
  }
}
```

#### 4. Control Group Response

Please discard predictions with abTestGroup control. We are using it to train our algorithm more efficiently:

```json
{
  "prediction": {
    "predictionType": "starter_pack",
    "userId": "2345",
    "predictedValue": "null",
    "abTestGroup": "control"
  }
}
```

**5. Standard HTTP Error Response Codes**

Standard HTTP error response codes apply for common HTTP issues (e.g., `404 Not Found`, `500 Internal Server Error`, etc.). In case of an error or timeout, treat the user as if they were in the control group.