# API reference

#### Overview

When the Assetario API is called, it provides a single json response. The possible replies include either a prediction, a list of predictions, an error message, or a null value.

#### Integration Options

Partners have 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.

#### API Request Fields

The API call is composed of mandatory and optional fields. **The complete set of optional fields to be passed in the body of the API call will be determined during the integration process.** They can include:

* **Offer Specific Field**: A list of offers available for prediction for a particular user during the API call.
* **Geo Data Field**: When the API is called server-side, provide the IP address of the end user's device. If unavailable, supply user location details, including country, state, city, and zip code.

#### Endpoint Details

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

#### Sample API Request

To request an IAP Personalization 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 '{
    # --- BASE FIELDS ---
    "userId": "2345",
    "predictionType": "starter_pack",
    "deviceMake": "apple",
    "deviceModel": "iphone9,3",
    "devicePlatformName": "iOS",
    "devicePlatformVersion": "14",
    "deviceFamily": "phone",
    "deviceLanguage": "eng",
    "installDate": "2022-01-01",
    "appVersion": "1.2.3",
    "cumulativeSpend": "123.45",
    "cumulativeNumberOfSessions": "123",
    # --- PREDICTION_TYPE SPECIFIC FIELDS ---
    "listAvailableOffers": "['10001', '10002', '10003', '10004']",
    "listUserTags": "['tag_1', 'tag_2']",
    "currentLevel": "10",
    "lastSevenDaySpend": "0.0",
    "clientIp": "192.168.100.1"
}'
```

{% hint style="danger" %}
**Note**: Ensure that the format for **`deviceModel`** and **`deviceMake`** matches the data dump's design. For instance, if using Appsflyer for device info collection, maintain Appsflyer’s format for  **`customFields`** the API request.
{% 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

**Response fields**

* **predictionType:** same as input
* **userId:** same as input
* **predictedValue:** the offer\_id or a set of offer\_ids to be shown to the user. If multiple offers are returned, the order matters.
* **abTestGroup:**  if Assetario administers the A/B test, the response also includes the user's test group as retrieved from the Assetario A/B Test Service. The value can either be **"personalized"** for users in the Assetario arm of the test or **"control"** for users who are not receiving an Assetario prediction.

**1. Correct Response - One Prediction**

The expected response when the API call is successful and returns a single prediction:

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

**2. Correct Response - List of Predictions**

The expected response when the API call is successful and returns a list of predictions:

```json
{
  "prediction": {
    "predictionType": "starter_pack",
    "userId": "2345",
    "predictedValue": [
      "1004",
      "1003",
      "1002"
    ],
    "abTestGroup": "personalized"
  }
}
```

**3. 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\""
  }
}
```

#### 4. Null Group Response

In case you receive a `null` response treat the user as if they were in the control group:

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

#### 5. 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"
  }
}
```

**6. 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/dynamic-offer-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.