Apps

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.

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

  1. customDimensions
  2. 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?