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:

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"
}'

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.

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.

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:

{
  "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:

{
  "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):

{
  "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:

{
  "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:

{
  "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.