Batch Interaction API

Use the Batch Interaction API to send interaction and interaction update requests in batches of up to 5,000 records using current or historical timestamps on the events. Batch interactions do not trigger online optimization points, but offline optimization points.

Authentication and authorization

MXO security framework uses OAuth 2.0 for authenticating access to data. For detailed information on how to create API credentials for a user and request an OAuth 2.0 token from MXO, see MXO API security.

Available API calls

We provide the API calls listed below:

MethodSummaryDetails
POST/batchv2/interactions/{siteKey}Process a batch of interaction requests.
POST/batchv2/interactions/{siteKey}/updateProcess a batch of interaction update requests.
GET/batchv2/interactions/{siteKey}/{batchId}Retrieve the current status of a batch processing job.
GET/batchv2/interactions/{siteKey}/{batchId}/errorRetrieve any errors that occurred during batch processing.

Example use cases

The Batch Interaction API is primarily used for two key purposes:

  1. Loading historical events at initial implementation to prime your workspace with data for analysis.

  2. Uploading events from a system MXO is not listening to.

Example parameters

FieldDescription
siteKeySite identifier key.

Example API call - Request

FieldDescription
Request MethodPOST
Request URL/batchv2/interactions/{siteKey}
Request HeadersworkspaceId: NzM3MjE Content-Type: application/json
Request Body 
{
        "customerKey": "ABC123",
        "customerKeyName": "ck",
        "uri": "https://website.com/home",
        "timestamp": 1697647862144,
        "properties": [
            {
                "name": "email_key",
                "value": "email1@medallia.com"
            },
            {
                "name": "someNumber",
                "value": 123
            }
        ]
}
{
        "customerKey": "ABC124",
        "customerKeyName": "ck",
        "uri": "https://website.com/home",
        "timestamp": 1697647862143,
        "properties": [
            {
                "name": "email_key",
                "value": "email2@medallia.com"
            },
            {
                "name": "someNumber",
                "value": 124
            }
        ]
}

Example API call - Response

Expected response code

200 Batch processed successfully

Expected response body

{
    "rejectedCount": 0,
    "acceptedCount": 0,
    "totalCount": 2,
    "batchId": "3df46dbd-59f4-406c-8462-374df55cbaaf"
}

Possible error response code

400 Bad request or duplicate batch ID

Error response body

{
	"errorMessage": "Batch ID: test already exists",
	"batchId": "3df46dbd-59f4-406c-8462-374df55cbaaf"
}