> For the complete documentation index, see [llms.txt](https://docs.assetario.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.assetario.com/docs/integration/iap-personalization-setup/dynamic-offer-personalization/api-reference.md).

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