Events API

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

Base URL

The base URL for the Events API varies depending on the data localization region for your mParticle account:

Authentication

The mParticle Events API can be authenticated with basic authentication in either of two ways:

1. If your HTTP client supports basic authentication, use your API key for “username” and your secret for “password”.

2. You can manually set the Authorization header in calls to the Events API by including your key and secret encoded together:

   • 2.1 Concatenate your key and secret together using 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 the resulting string as the authorization header in your HTTP requests: Authorization: Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

JSON format

The following examples demonstrate how to execute a general request to the Events API, however, the size of an example request body exercising every available property and parameter is too large to include. For a complete reference of the Events API schema that lists each property and parameter, see the JSON reference.

Open API spec

Use the Open API (previously known as Swagger) specification or similar tools to generate helper SDKs (using Swagger Codegen or OpenAPI Generator) for the Events API:

Events API Open API Spec

Rate limits

mParticle imposes default service limits on server-to-server data transfers using the Events API. For the specific limits, see Default Service Limits.

Maximizing performance

When sending large amounts of data to the Events API, use efficient batching strategies to prevent drops in performance.

Remember that one event batch includes an array than can contain one or more events. If you are tracking a large number of events that are all triggered by a single user, combine as many events as possible in a single batch based on a predetermined rate, such as a set number of events per timespan or a set number of events per user. Sending one batch for each event incurs a noticeable drop in performance.

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

Event batches require the following:

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

Exceeding these limits results in throttling.

Upload event data

Upload an event batch

POST https://s2s.{pod}.mparticle.com/v2/events

Example cURL request

curl --location --request POST 'https://s2s.{pod}.mparticle.com/v2/events' \
--header 'Authorization: Basic {your-api-key}:{your-api-secret}' --data-raw '{ your-event-batch }'

Example JSON request body

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

Response

A successful request receives a 200 Accepted response.

Upload multiple event batches

POST https://s2s.{pod}.mparticle.com/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 still receive a 202 Accepted response.

Don’t use this URL 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, use the historical endpoint.

Example cURL request

curl --location --request POST 'https://s2s.{pod}.mparticle.com/v2/bulkevents' \
--header 'Authorization: Basic {your-api-key}:{your-api-secret}' --data-raw '{ array-of-event-batches }'

Example JSON request body

[
   {
      "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"
   }
]

Response

A successful request receives a 202 Accepted response.

Upload a historical event batch

POST https://s2s.{pod}.mparticle.com/v2/bulkevents/historical

This path accepts the same JSON payload as /v2/bulkevents and should be used to upload historical 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.

Historical data 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.

Example cURL request

curl --location --request POST 'https://s2s.{pod}.mparticle.com/v2/bulkevents/historical' \
--header 'Authorization: Basic {your-api-key}:{your-api-secret}' --data-raw '{ historical-event-batch }'

Example JSON request body

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

Response

A successful request receives a 202 Accepted response.

Error handling

In some cases, the server provides additional information in the response body. If no additional information is available, the response body will be omitted and you will only receive the status code and message.

Example response body for an unsuccessful request

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