Platform API Overview

The mParticle platform API allows you to RESTfully create and update a number of entities as well as configure services to forward data to.

Platform API resource groups

For a complete API reference for each set of Platform API resources, see the following:

• Accounts

• Apps

  • Includes app platforms and app services
• Audiences
• Calculated attributes
• Data points
• Feeds
• Field transformations
• Services
• Users
• Workspaces

The rest of this page provides general usage guidelines applicable to all resources contained in the Platform API.

General Platform API usage

Base URL

The Platform API is located at https://api.mparticle.com.

Prerequisites to accessing the API

To authenticate to the Platform API, use the API Credentials interface to create a Client ID and Secret, then use these credentials to fetch an OAuth access token.

Authentication

Once your API user is set up, you can authenticate by issuing a POST request to mParticle’s SSO token endpoint.

https://sso.auth.mparticle.com/oauth/token

The JSON body of the request must contain:

• client_id - your Client ID, issued by mParticle
• client_secret - your Client Secret, issued by mParticle
• audience - set to a value of "https://api.mparticle.com"
• grant_type - set to a value of "client_credentials"

Curl Syntax

curl --request POST \
  --url https://sso.auth.mparticle.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"...","client_secret":"...","audience":"https://api.mparticle.com","grant_type":"client_credentials"}'

Sample Raw HTTP Request

POST /oauth/token HTTP/1.1
Host: sso.auth.mparticle.com
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "audience": "https://api.mparticle.com",
  "grant_type": "client_credentials"
}

Using your Bearer Token

A successful POST request to the token endpoint will result in a JSON response as follows:

{
  "access_token": "YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-",
  "expires_in" : 28800,
  "token_type": "Bearer"
}

Subsequent requests to the API can now be authorized by setting the Authorization header as follows:

Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-

Versioning

Once you have authenticated, the API resources can be accessed at https://api.mparticle.com/v1/. Subsequent updates to the API that introduce breaking changes will be published with a new version number in the URL.

Specifying your Account ID

Unless otherwise stated in the documentation for the specific resource group you are using, all API calls require you to pass in your AccountId as a querystring parameter. Forgetting to add the AccountId parameter when required will result in a 401 Unauthorized response. All subsequent entities that you work with will be within the scope of the chosen account ID. Attempting to access or modify entities outside the specified Account ID scope will return 404 - Not Found.

Sending Data

Unless otherwise stated in the documentation for the specific resource group you are using, all POST/PUT requests should send JSON as the Request Payload, with Content-Type set to application/json.

Return Data

Unless otherwise stated in the documentation for the specific resource group you are using, if an API request returns data, it will be wrapped in a common JSON structure.

{
  "data": [],
  "dataType": "app",
  "errors": [
    {
        "code": "VALIDATION_ERROR",
        "message": "Error message here"
    }
  ]
}

One or more entities will be returned as an array in the data property. If errors were encountered, they will be available as an array of error objects.

Status Codes

The following table lists the status codes that are returned by API requests:

Cross Origin Resource Sharing

The mParticle REST API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.