HTTP API

Overview

mParticle provides an HTTP-based Events API than can be used to power mParticle’s Audience platform as well as to supplement data collected via our mobile SDKs.

Endpoint

Our HTTP endpoint is: https://s2s.mparticle.com

JSON Format

Please reference the JSON reference for the precise API schema.

Paths

/v2/events

https://s2s.mparticle.com/v2/events

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

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

/v2/bulkevents

https://s2s.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 will still get an “Accepted” response.

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

/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.

mParticle Feature Effect of historical data
Event and Data Warehouse Outputs Not forwarded downstream.
Audience No change to Real-time or Lifetime audiences. Data is subject to existing date-range retention limits. Real-time audiences have a 30 day look-back for most customers.
User Activity No change; Events visible in date order.
Identity and Profiles No change

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 authentication 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.

Response

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

Status Code Notes
202 Accepted The POST was accepted.
400 Bad Request The request JSON was malformed JSON or had missing fields.
401 Unauthorized The authentication header is missing.
403 Forbidden The authentication header is present, but invalid.
429 Too Many Requests You have exceeded your provisioned limit. We recommend retrying your request in an exponential backoff pattern
503 Service Unavailable We recommend retrying your request in an exponential backoff pattern
5xx Server Error A server-side error has occured, please try your request again.

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.

Was this page helpful?