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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.assetario.com/docs/integration/iap-personalization-setup/contextual-price-personalization/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.