Developers

Platform API

Get a single app

GET /apps/1?accountId=1

Example cURL request

curl -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" -X GET https://api.mparticle.com/v1/apps/1?accountId=1

Response

{
  "data": [
    {
      "name": "Test App",
      "platforms": [
        {
          "application_id": 1,
          "os": "Android",
          "access_keys": [
            {
              "key": "AccessKey",
              "secret": null,
              "data_type": "token"
            }
          ],
          "crash_handling": "AppDefined",
          "network_performance": "AppDefined",
          "social_mode": "AppDefined",
          "profile_merging": false,
          "push_attribution_timer": 30,
          "last_modified_on": "2014-11-05T20:09:46.577",
          "data_type": "platform",
          "created_on": "2014-06-11T19:43:48.697"
        }
      ],
      "last_modified_on": "2014-06-11T19:43:45.617",
      "data_type": "application",
      "id": 1,
      "created_on": "2014-06-11T19:43:45.617"
    }
  ],
  "dataType": "application",
  "errors": null
}

Get all apps

GET /apps?accountId=1

Example cURL request

curl -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" -X GET https://api.mparticle.com/v1/apps?accountId=1

Response

{
  "data": [
    {
      "name": "Test App",
      "platforms": [
        {
          "application_id": 1,
          "os": "Android",
          "access_keys": [
            {
              "key": "AccessKey",
              "secret": null,
              "data_type": "token"
            }
          ],
          "crash_handling": "AppDefined",
          "network_performance": "AppDefined",
          "social_mode": "AppDefined",
          "profile_merging": false,
          "push_attribution_timer": 30,
          "last_modified_on": "2014-11-05T20:09:46.577",
          "data_type": "platform",
          "created_on": "2014-06-11T19:43:48.697"
        }
      ],
      "last_modified_on": "2014-06-11T19:43:45.617",
      "data_type": "application",
      "id": 1,
      "created_on": "2014-06-11T19:43:45.617"
    }
  ],
  "dataType": "application",
  "errors": null
}

Update an app

PUT /apps/1?accountId=1

Example cURL request

curl \
  -X PUT \
  -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" \
  -H "Content-Type: application/json"  \
  -d "{\"name\": \"Updated Name\"}" \
  "https://api.mparticle.com/v1/apps/1?accountId=1"

Response

{
  "name": "Test App New Name"
}

Request body parameters

Name	Type	Description
name	`string`	The name of the app.

Errors

Name
App name must be specified.

Create an app

POST /apps?accountId=1

Example cURL request

curl \
  -X POST \
  -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"Test App\", \"platforms\":[{\"os\": \"iOS\"},{\"os\": \"Android\"}]}" \
  "https://api.mparticle.com/v1/apps?accountId=1"

Example HTTP Request

{
  "name": "Test App",
  "platforms": [
    {
      "os": "iOS"
    },
    {
      "os": "Android"
    }
  ]
}

Response

{
  "data": [
    {
      "name": "Test App",
      "platforms": [
        {
          "application_id": 1,
          "os": "iOS",
          "access_keys": [
            {
              "key": "AccessKey",
              "secret": "AccessSecret",
              "data_type": "token"
            }
          ],
          "crash_handling": null,
          "network_performance": null,
          "social_mode": null,
          "profile_merging": true,
          "push_attribution_timer": 30,
          "last_modified_on": "2015-03-11T12:07:08.077",
          "data_type": "platform",
          "created_on": "2015-03-11T12:07:08.077"
        }
      ],
      "last_modified_on": "2015-03-11T12:07:07.877",
      "data_type": "application",
      "id": 1,
      "created_on": "2015-03-11T12:07:07.877"
    }
  ],
  "dataType": "application",
  "errors": null
}

Request body parameters

Name	Type	Description
name	string	The name of the app
platforms	array	Array of platforms to create for the app in the format of `{"os": "iOS"}`. Valid values for the “os” field include “iOS”, “tvOS”, “Android”, “MobileWeb”, “Roku”, “Alexa”, “SmartTV”, “FireTV”, and “Xbox”

Errors

Name
Exceeded app limit.
App name already exists.
App must have at least one platform selected.
App name not specified.
Invalid as specified.

Creating a new app or app platform will generate a new Access Key and Secret for that app platform, which can be accessed through the “access_keys”. Note that this is the only time the Secret is transmitted - subsequent GET requests will only return the Access Key.

Delete an app

DELETE /apps/1?accountId=1

Example cURL request

curl \
  -X DELETE \
  -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-"  \
  https://api.mparticle.com/v1/apps/1?accountId=1

Errors

Name
Deleting an app that has active platforms is not allowed.

Get a single app platform

GET /apps/1/platforms/android?accountId=1

Example cURL request

curl \
  -X GET \
  -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" \
  "https://api.mparticle.com/v1/apps/1/platforms/android?accountId=1" \

Response

{
  "data": [
    {
      "application_id": 1,
      "os": "Android",
      "access_keys": [
        {
          "key": "AccessKey",
          "secret": null,
          "data_type": "token"
        }
      ],
      "crash_handling": "AppDefined",
      "network_performance": "AppDefined",
      "social_mode": "AppDefined",
      "profile_merging": false,
      "push_attribution_timer": 30,
      "last_modified_on": "2014-11-05T20:09:46.577",
      "data_type": "platform",
      "created_on": "2014-06-11T19:43:48.697"
    }
  ],
  "dataType": "platform",
  "errors": null
}

Get all app platforms

GET /apps/1/platforms?accountId=1

Example cURL request

curl \
  -X GET \
  -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" \
  "https://api.mparticle.com/v1/apps/1/platforms?accountId=1"

Response

{
  "data": [
    {
      "application_id": 1,
      "os": "Android",
      "access_keys": [
        {
          "key": "AccessKey",
          "secret": null,
          "data_type": "token"
        }
      ],
      "crash_handling": "AppDefined",
      "network_performance": "AppDefined",
      "social_mode": "AppDefined",
      "profile_merging": false,
      "push_attribution_timer": 30,
      "last_modified_on": "2014-11-05T20:09:46.577",
      "data_type": "platform",
      "created_on": "2014-06-11T19:43:48.697"
    }
  ],
  "dataType": "platform",
  "errors": null
}

Update an app platform

PUT /apps/1/platforms/ios?accountId=1

Example cURL request

curl \
  -X PUT \
  -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" \
  -H "Content-Type: application/json" \
  -d "{\"profile_merging\": true,\"push_attribution_timer\": 30,\"crash_handling\": \"ForceCatch\",\"network_performance\": \"ForceTrue\",\"social_mode\": \"FacebookAndTwitter\"}" \
  "https://api.mparticle.com/v1/apps/1/platforms/ios?accountId=1"

Example HTTP request

{
  "profile_merging": true,
  "push_attribution_timer": 30,
  "crash_handling": "ForceCatch",
  "network_performance": "ForceTrue",
  "social_mode": "FacebookAndTwitter"
}

Request body parameters

Name	Type	Description
profile_merging	`bool`	Enable or disable profile merging
push_attribution_timer	`int`	Push attribution timer in minutes
crash_handling	`string`	“AppDefined” or “ForceCatch” or “ForceIgnore”
network_performance	`string`	“AppDefined” or “ForceTrue” or “ForceFalse”
social_mode	`string`	“AppDefined” or “Facebook” or “Twitter” or “FacebookAndTwitter”

Create an app platform

POST apps/1/platforms?accountId=1

Example cURL request

curl \
  -X POST \
  -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" \
  -H "Content-Type: application/json" \
  -d "{\"os\": \"android\",\"profile_merging\": true,\"push_attribution_timer\": 30,\"crash_handling\": \"ForceCatch\",\"network_performance\": \"ForceTrue\",\"social_mode\": \"FacebookAndTwitter\"}" \
  "https://api.mparticle.com/v1/apps/1/platforms?accountId=1"

Example HTTP request

{
  "os": "android",
  "profile_merging": true,
  "push_attribution_timer": 30,
  "crash_handling": "ForceCatch",
  "network_performance": "ForceTrue",
  "social_mode": "FacebookAndTwitter"
}

Response

{
  "data": [
    {
      "application_id": 1,
      "os": "Android",
      "access_keys": [
        {
          "key": "AccessKey",
          "secret": "AccessSecret",
          "data_type": "token"
        }
      ],
      "crash_handling": "AppDefined",
      "network_performance": "AppDefined",
      "social_mode": "AppDefined",
      "profile_merging": false,
      "push_attribution_timer": 30,
      "last_modified_on": "2014-11-05T20:09:46.577",
      "data_type": "platform",
      "created_on": "2014-06-11T19:43:48.697"
    }
  ],
  "dataType": "platform",
  "errors": null
}

Request body parameters

Name	Type	Description
os	`string`	Valid values for the “os” field include “iOS”, “tvOS”, “Android”, “MobileWeb”, “Roku”, “Alexa”, “SmartTV”, “FireTV”, and “Xbox”
profile_merging	`bool`	Enable or disable profile merging
push_attribution_timer	`int`	Push attribution timer in minutes
crash_handling	`string`	“AppDefined” or “ForceCatch” or “ForceIgnore”
network_performance	`string`	“AppDefined” or “ForceTrue” or “ForceFalse”
social_mode	`string`	“AppDefined” or “Facebook” or “Twitter” or “FacebookAndTwitter”

Errors

Name
Could not create platform: App does not exist or you do not have access.
Invalid os specified.
Platform already exists for the specified App.

Delete an app platform

DELETE /apps/1/platforms/ios?accountId=1

Example cURL request

curl \
  -X DELETE \
  -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" \
  "https://api.mparticle.com/v1/apps/1/platforms/ios?accountId=1"

Get all services for an app platform

GET /apps/1/platforms/ios/services?accountId=1

Example cURL request

curl \
  -X GET \
  -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" \
  "https://api.mparticle.com/v1/apps/1/platforms/ios/services?accountId=1`"

Response

{
  "data": [
    {
      "account": "Default Account",
      "name": "GoogleAnalyticsEventForwarder",
      "isActive": true,
      "isVisible": true,
      "settings": [
        {
          "name": "apiKey",
          "value": "*********** Key",
          "isConfidential": true
        }
      ],
      "data_type": "service"
    }
  ],
  "dataType": "service",
  "errors": null
}

Configure a service for an app platform

PUT /apps/1/platforms/ios/services?accountId=1

Example cURL request

curl \
  -X PUT \
  -H "Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-" \
  -H "Content-Type: application/json" \
  -d "{\"account\": \"Default Account\", \"name\":\"GoogleAnalyticsEventForwarder\",\"isActive\":true,\"isVisible\": true,\"settings\":[{\"name\":\"apiKey\",\"value\":\"My Test App Key\"}]}" \
  "https://api.mparticle.com/v1/apps/1/platforms/ios/services?accountId=1"

Example HTTP request

{
  "account": "Default Account",
  "name":"GoogleAnalyticsEventForwarder",
  "isActive":true,
  "isVisible": true,
  "settings":[
    {
      "name":"apiKey",
      "value":"My Test App Key"
    }
  ]
}

Request body parameters

Name	Type	Description
account	`string`	The name of the account you wish to configure.
name	`string`	The name of the service you wish to configure.
isActive	`bool`	Controls whether data is actually pushed to the service.
isVisible	`bool`	Whether the service is visible in the UI.
settings	`array`	Array of setting objects.

Errors

Name
Specified service not found.
Service does not support app platform.
Invalid settings entered while updating the service.
Provided setting not found.
Required setting not provided.
Setting value is required.

To discover what settings are available for each service, you can call https://api.mparticle.com/v1/services?accountId=1 to discover all services and supported settings.

The “account” parameter allows you to forward data to more than one account per service. It is internal to mParticle, and can be set to any name of your choosing. If omitted or set to null, the account name will be set to “Default Account”.

The “isVisible” flag allows you to create services that forward data in the background, but are not visible in the mParticle UI. This allows you to have two active forwarders per combination of app platform and service. This field is not required and will default to true if omitted.

Custom Service Settings

Google Analytics Settings

Google Analytics has a few configuration settings which require additional details to be set. These settings are listed below and are noted with a type of Custom in the services call.:

customDimensions
customMetrics

Example

{
  "account": "Default Account",
  "name":"GoogleAnalyticsEventForwarder",
  "isActive":true,
  "isVisible": true,
  "settings":[
    {
      "name":"apiKey",
      "value":"My Test App Key"
    },
    {
      "name":"customDimensions",
      "value":"[{\"maptype\":\"EventAttributeClass.Name\",\"map\":\"Bitcoins\",\"value\":\"Dimension 3\"}]"
    }
  ]
}

Check Google Analytics for additional details on these settings and the limits on the supported custom dimensions and metrics. The value for these settings is a json array containing objects with maptype, map and value. You need to indicate if you are using an Event Attribute or a User Attribute, and then specify the mapping to the Custom Dimension or Custom Metric.

Field	Description	Notes & examples
maptype	This indicates if you are passing an event or user attribute into the map.	`EventAttributeClass.Name` or `UserAttributeClass.Name` or `ProductAttributeClass.Name`.
map	The name of the event attribute, user attribute or product attribute. The attribute name must match exactly or it will not map correctly.	For example, `Bitcoins`.
value	The custom dimension or custom metric for the mapping.	For example, `Dimension 3` or `Metric 1`

Was this page helpful?

Apps

Get a single app

Example cURL request

Response

Get all apps

Example cURL request

Response

Update an app

Example cURL request

Response

Request body parameters

Errors

Create an app

Example cURL request

Example HTTP Request

Response

Request body parameters

Errors

Delete an app

Example cURL request

Errors

Get a single app platform

Example cURL request

Response

Get all app platforms

Example cURL request

Response

Update an app platform

Example cURL request

Example HTTP request

Request body parameters

Create an app platform

Example cURL request

Example HTTP request

Response

Request body parameters

Errors

Delete an app platform

Example cURL request

Get all services for an app platform

Example cURL request

Response

Configure a service for an app platform

Example cURL request

Example HTTP request

Request body parameters

Errors

Custom Service Settings

Example