HTTP API

Overview

mParticle provides an HTTP-based Events API that can be used to collect data from your backend systems.

Endpoint

The HTTP endpoint to send data is based on which Pod your account is hosted:

JSON Format

Please reference the JSON reference for the precise API schema.

Open API

You can use the Open API specification (also known as Swagger) below to generate helper SDKs (using Swagger Codegen or OpenAPI Generator) for the Events API:

Events API Open API Spec

Paths

/v2/events

This path accepts a JSON event batch. See our JSON documentation for additional information.

This path should not be used to upload historical data older than 30 days, as this could impact downstream processes such as audience calculation. To upload historical data older than 30 days, please use the historical endpoint.

{
    "events" : [
        {
            "data" : {},
            "event_type" : "custom_event"
        }
    ],
    "device_info" : {},
    "user_attributes" : {},
    "deleted_user_attributes" : [],
    "user_identities" : {},
    "application_info" : {},
    "schema_version": 2,
    "environment": "production",
    "context" : {},
    "ip" : "172.217.12.142"
}

/v2/bulkevents

This path accepts a JSON array of event batches. See our JSON documentation for additional information.

You may not send more than 100 EVENT DATA items per request. If some event batches succeed and some event batches fail, you will still get an “Accepted” response.

This path should not be used to upload historical data older than 30 days, as this could impact downstream processes such as audience calculation. To upload historical data older than 30 days, please use the historical endpoint.

Please see the format below containing an array of JSON event batches.

[
    {
        "events" : [
            {
                "data" : {},
                "event_type" : "custom_event"
            }
        ],
        "device_info" : {},
        "user_attributes" : {},
        "deleted_user_attributes" : [],
        "user_identities" : {},
        "application_info" : {},
        "schema_version": 2,
        "environment" : "production",
        "context" : {},
        "ip" : "172.217.12.142"
    },
    {
        "events" : [
            {
                "data" : {},
                "event_type" : "custom_event"
            }
        ],
        "device_info" : {},
        "user_attributes" : {},
        "deleted_user_attributes" : [],
        "user_identities" : {},
        "application_info" : {},
        "schema_version" : 2,
        "environment" : "production",
        "context" : {},
        "ip" : "172.217.12.142"
    }
]

/v2/bulkevents/historical

This path accepts the same JSON payload as /v2/bulkevents and should be used to upload historical backfill data more than 30 days old. Data forwarded to the historical endpoint is subject to special requirements and is processed differently.

Historical data requirements

A batch received by the historical data endpoint will not be processed if any of the following are true:

• The batch contains no events,
• Any event in the batch does not contain the timestamp_unixtime_ms property,
• The value of any timestamp_unixtime_ms is less than 72 hours old.

Processing

The historical API endpoint behaves nearly identically to the events and bulkevents endpoints with one key difference: data is not forwarded to connected event and data warehouses.

Authentication

The HTTP APIs are secured via basic authentication.

You can authenticate in 2 ways:

1. Many HTTP clients support basic authentication out of the box. Use your API key for the “username” and your API secret for “password”.

2. Manually set the Authorization header by encoding your key and secret together:

   2.1 Concatenate your application key and secret together with a colon (:) separating the two:

   example-api-key:example-api-secret

   2.2 Base64 with UTF-8 encode the result:

   ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

   2.3 Prefix the encoded string with the authorization method, including a space:

   Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

   2.4 Set resulting string as the Authorization header in your HTTP requests:

   Authorization: Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

Data Format

You must POST a JSON Document to the endpoint. Reference the JSON documentation for details.

Rate Limits

mParticle recieves data across many channels, and limits are not always enforced in the same way for each channel. Default service limits affect S2S or ‘server-to-server’ data. S2S data includes data received via the Events API, Calculated Attributes Seeding API, and from partner feeds.

For more information about default service limits related to event batches, see Default Service Limits.

Response

You should inspect the status code of the response to determine if the POST has been accepted or if an error occurred.

Response Body

In some cases, the server can provide additional information the error that occurred in the response body.

The response body is optionally sent from the server and will not be included if additional details on the error are not known.

{
    "errors" :
    [
        {
            "code" : "BAD_REQUEST",
            "message" : "Required event field \"event_type\" is missing or empty."
        }
    ]
}

Maximizing Performance

In order to maintain high throughput performance for large quantities of event data via the HTTP API, pay attention to how you compile individual events into batches. Each batch contains an event array which can hold multiple events, as long as they are for the same user.

If you are generating a lot of event data, sending a full batch for each individual event in realtime will negatively impact performance. Instead, send a combined event batch either at a set time interval, or after a given number of events for each user.

You can further reduce the number of HTTP requests by grouping together up to 100 event batches for multiple users together and forwarding them to the /bulkevents endpoint.

When creating event batches remember the following:

• Each batch should contain data for only one user.
• Each batch should not exceed 128kb in size.
• A request to /bulkevents should contain no more than 100 batches.