Interaction Upload API

Bulk API to insert Interaction records. This endpoint accepts POST requests with JSON data containing an array of Interaction records wrapped in a dictionary:

POST /v1/interactions

{"data": [interaction_1, interaction_2, interaction_3]}

For real-time tracking, we recommend sending the interaction records to this API as soon as the interactions take place. This API is also ideal for bulk-inserting historical records that your site collected before using Miso. Miso can analyze the historical records and provide personalization for your users from the get-go. We recommend limiting your calls to around 10,000 records at a time to avoid memory issues or timeout risks.

Anonymous users

For users who did not sign in, we can still make recommendations for them by tracking their anonymous_id, which is a pseudo-unique substitute for the user_id. The personalization and search APIs all accept anonymous_id in the place of user_id to return tailored results for anonymous users.

When an anonymous user later signs in and the user_id and anonymous_id are both present, the anonymous_id will be linked to the user_id along with the past interactions associated with it.

The typical mechanism to generate an anonymous_id is to use cookies or the browser localStorage. However, if you don't collect such information in your historical records, a hash of the IP address, optionally combined with the User-Agent string, is also a reasonable substitute for anonymous_id, and is most likely collected by your web server logs already.

Schema validation

The Interaction Upload API will validate the inserted records against the API schema. Any schema errors will cause the whole request to fail, and none of the records will be inserted (status_code=422). You should check the response.errors field to see if there are any errors.

For example, the response below means there are no errors (status_code=200):

{
    "message": "success"
}

Any schema error will cause the whole request to fail: the API will return status_code=422, and none of the records will be inserted. You should check data field in the response to see where the errors are located. For example, the response below means there are schema errors in the interaction record at index 0:

{
    "errors": true, // there are errors. please check!
    "message": "None of the records were inserted because at least one of them contained schema errors. Please see the `data` field for details.",
    "data": [
        "data.0.product_ids is invalid. The attribute was expected to be of type ''array', 'null'' but type 'string' was given.",
        "data.0.timestamp is invalid. The attribute should match the 'date-time' format."
    ]
}