HTTP API

Overview

mParticle provides an HTTP-based Server 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

Swagger Documentation

For a full API reference, download the Swagger spec file and open it in the Swagger Editor.

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

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.