Platform API Overview
Accounts
Apps
Audiences
Calculated Attributes
Data Points
Feeds
Field Transformations
Services
Users
Workspaces
Data Subject Request API Version 1 and 2
Data Subject Request API Version 3
Warehouse Sync API Overview
Warehouse Sync API Tutorial
Warehouse Sync API Reference
Data Mapping
Warehouse Sync SQL Reference
Warehouse Sync Troubleshooting Guide
ComposeID
Warehouse Sync API v2 Migration
Bulk Profile Deletion API Reference
Custom Access Roles API
Calculated Attributes Seeding API
Data Planning API
Group Identity API Reference
Pixel Service
Profile API
Events API
mParticle JSON Schema Reference
IDSync
AMP SDK
Initialization
Configuration
Network Security Configuration
Event Tracking
User Attributes
IDSync
Screen Events
Commerce Events
Location Tracking
Media
Kits
Application State and Session Management
Data Privacy Controls
Error Tracking
Opt Out
Push Notifications
WebView Integration
Logger
Preventing Blocked HTTP Traffic with CNAME
Linting Data Plans
Troubleshooting the Android SDK
API Reference
Upgrade to Version 5
Cordova Plugin
Identity
Direct URL Routing FAQ
Web
Android
iOS
Workspace Switching
Initialization
Configuration
Event Tracking
User Attributes
IDSync
Screen Tracking
Commerce Events
Location Tracking
Media
Kits
Application State and Session Management
Data Privacy Controls
Error Tracking
Opt Out
Push Notifications
Webview Integration
Upload Frequency
App Extensions
Preventing Blocked HTTP Traffic with CNAME
Linting Data Plans
Troubleshooting iOS SDK
Social Networks
iOS 14 Guide
iOS 15 FAQ
iOS 16 FAQ
iOS 17 FAQ
iOS 18 FAQ
API Reference
Upgrade to Version 7
Getting Started
Identity
Upload Frequency
Getting Started
Opt Out
Initialize the SDK
Event Tracking
Commerce Tracking
Error Tracking
Screen Tracking
Identity
Location Tracking
Session Management
Initialization
Configuration
Content Security Policy
Event Tracking
User Attributes
IDSync
Page View Tracking
Commerce Events
Location Tracking
Media
Kits
Application State and Session Management
Data Privacy Controls
Error Tracking
Opt Out
Custom Logger
Persistence
Native Web Views
Self-Hosting
Multiple Instances
Web SDK via Google Tag Manager
Preventing Blocked HTTP Traffic with CNAME
Facebook Instant Articles
Troubleshooting the Web SDK
Browser Compatibility
Linting Data Plans
API Reference
Upgrade to Version 2 of the SDK
Getting Started
Identity
Alexa
Overview
Step 1. Create an input
Step 2. Verify your input
Step 3. Set up your output
Step 4. Create a connection
Step 5. Verify your connection
Step 6. Track events
Step 7. Track user data
Step 8. Create a data plan
Step 9. Test your local app
Overview
Step 1. Create an input
Step 2. Verify your input
Step 3. Set up your output
Step 4. Create a connection
Step 5. Verify your connection
Step 6. Track events
Step 7. Track user data
Step 8. Create a data plan
Step 1. Create an input
Step 2. Create an output
Step 3. Verify output
Node SDK
Go SDK
Python SDK
Ruby SDK
Java SDK
Introduction
Outbound Integrations
Firehose Java SDK
Inbound Integrations
Compose ID
Data Hosting Locations
Glossary
Migrate from Segment to mParticle
Migrate from Segment to Client-side mParticle
Migrate from Segment to Server-side mParticle
Segment-to-mParticle Migration Reference
Rules Developer Guide
API Credential Management
The Developer's Guided Journey to mParticle
Overview
Overview
User Profiles
Overview
Create and Manage Group Definitions
Calculated Attributes Overview
Using Calculated Attributes
Create with AI Assistance
Calculated Attributes Reference
What are predictive attributes?
Create an Input
Start capturing data
Connect an Event Output
Create an Audience
Connect an Audience Output
Transform and Enhance Your Data
Usage and Billing Report
The new mParticle Experience
The Overview Map
Observability Overview
Observability User Guide
Observability Troubleshooting Examples
Observability Span Glossary
Event Forwarding
Notification Center (Early Access)
System Alerts
Trends
Introduction
Data Retention
Data Catalog
Connections
Activity
Data Plans
Live Stream
Filters
Rules
Blocked Data Backfill Guide
Tiered Events
mParticle Users and Roles
Analytics Free Trial
Troubleshooting mParticle
Usage metering for value-based pricing (VBP)
Audiences Overview
Create an Audience
Connect an Audience
Manage Audiences
FAQ
Real-time Audiences (Legacy)
Standard Audiences (Legacy)
Predictive Audiences Overview
Using Predictive Audiences
IDSync Overview
Use Cases for IDSync
Components of IDSync
Store and Organize User Data
Identify Users
Default IDSync Configuration
Profile Conversion Strategy
Profile Link Strategy
Profile Isolation Strategy
Best Match Strategy
Aliasing
Introduction
Core Analytics (Beta)
Sync and Activate Analytics User Segments in mParticle
User Segment Activation
Welcome Page Announcements
Project Settings
Roles and Teammates
Organization Settings
Global Project Filters
Portfolio Analytics
Analytics Data Manager Overview
Events
Event Properties
User Properties
Revenue Mapping
Export Data
UTM Guide
Analyses Introduction
Getting Started
Visualization Options
For Clauses
Date Range and Time Settings
Calculator
Numerical Settings
Assisted Analysis
Properties Explorer
Frequency in Segmentation
Trends in Segmentation
Did [not] Perform Clauses
Cumulative vs. Non-Cumulative Analysis in Segmentation
Total Count of vs. Users Who Performed
Save Your Segmentation Analysis
Export Results in Segmentation
Explore Users from Segmentation
Getting Started with Funnels
Group By Settings
Conversion Window
Tracking Properties
Date Range and Time Settings
Visualization Options
Interpreting a Funnel Analysis
Group By
Filters
Conversion over Time
Conversion Order
Trends
Funnel Direction
Multi-path Funnels
Analyze as Cohort from Funnel
Save a Funnel Analysis
Explore Users from a Funnel
Export Results from a Funnel
Saved Analyses
Manage Analyses in Dashboards
Query Builder Overview
Data Dictionary
Modify Filters With And/Or Clauses
Query-time Sampling
Query Notes
Filter Where Clauses
Event vs. User Properties
Group By Clauses
Annotations
Cross-tool Compatibility
Apply All for Filter Where Clauses
Date Range and Time Settings Overview
User Attributes at Event Time
Understanding the Screen View Event
User Aliasing
Dashboards––Getting Started
Manage Dashboards
Dashboard Filters
Organize Dashboards
Scheduled Reports
Favorites
Time and Interval Settings in Dashboards
Query Notes in Dashboards
The Demo Environment
Keyboard Shortcuts
User Segments
Warehouse Sync
Data Privacy Controls
Data Subject Requests
Default Service Limits
Feeds
Cross-Account Audience Sharing
Approved Sub-Processors
Import Data with CSV Files
CSV File Reference
Glossary
Video Index
Single Sign-On (SSO)
Setup Examples
Introduction
Introduction
Introduction
Rudderstack
Google Tag Manager
Segment
Advanced Data Warehouse Settings
AWS Kinesis (Snowplow)
AWS Redshift (Define Your Own Schema)
AWS S3 Integration (Define Your Own Schema)
AWS S3 (Snowplow Schema)
BigQuery (Snowplow Schema)
BigQuery Firebase Schema
BigQuery (Define Your Own Schema)
GCP BigQuery Export
Snowplow Schema Overview
Snowflake (Snowplow Schema)
Snowflake (Define Your Own Schema)
Aliasing
The Identity HTTP API is utilized by the mParticle iOS, Android, and Web SDKs, and can also be used directly. See our IDSync guide for more information.
The mParticle Identity endpoint is available at:
https://identity.mparticle.com/v1For a full API reference, download the Swagger spec file and open it in the Swagger Editor.
The mParticle Identity API supports three methods of authentication:
All methods use platform-level API credentials. To find or create API credentials, navigate to Setup > Inputs in the mParticle dashboard, and select a platform (iOS, Android, Web, etc).
You can use basic authentication in 2 ways:
Manually set the authentication header by encoding your key and secret together:
2.1 Concatenate your API Key and API 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 Basic, including a space:
Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==
2.4 Set resulting string as the Authorization header in your HTTP requests:
Authorization: Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==
The HMAC digest authentication method should be used by all clients of the Identity API. The requirements are as follows:
x-mp-key header in the request.20170712T224127Z) as the Date header in the request.x-mp-signature header in the request.Concatenate the following:
POST) + newline20170712T224127Z) + newline/v1/identify) + Body of the requestFor example, your concatenation should look similar to:
POST
20170712T224127Z
/v1/identify{"client_sdk":{"platform":"android","sdk_vendor":"mparticle","sdk_version":"5.0.0"},"environment":"development","request_timestamp_ms":1499875715564,"request_id":"ad58a7c1-cf35-4be5-8c42-a09989f85cc1","known_identities":{"android_uuid":"f924f1e5707b34b7"}}Encode the string
Using the utf-8 bytes of your mParticle platform API Secret (matching the API Key in the x-mp-key header), and the string above, create a byte encoding using HMAC SHA256 and convert the result to a hexadecimal string. Include that string as the x-mp-signature header.
On devices that cannot support the above algorithm, you may use only the mParticle platform API Key for authentication, by providing it as the x-mp-key header. This is only selectively enabled - and is disabled by default.
/identifyThe identify request should be used to establish a user identity, typically when an app is first initialized. It accepts a set of known identities and returns an mParticle ID, in accordance with an Identity Strategy. You should provide all available identifying information for the given user.
The identify, search, login, and logout requests accept a POST body with the following schema.
You must always supply at least one known identity
{
"client_sdk": {
"platform": "ios",
"sdk_vendor": "string",
"sdk_version": "string"
},
"context": "string",
"environment": "production",
"request_id": "string",
"request_timestamp_ms": 0,
"previous_mpid": "string",
"known_identities": {
"ios_idfa": "string",
"android_aaid": "string",
"amp_id": "string",
"android_uuid": "string",
"ios_idfv": "string",
"push_token": "string",
"roku_publisher_id": "string",
"roku_aid": "string",
"fire_aid": "string",
"customerid": "string",
"email": "string",
"facebook": "string",
"facebookcustomaudienceid": "string",
"google": "string",
"microsoft": "string",
"other": "string",
"twitter": "string",
"yahoo": "string",
"device_application_stamp": "string"
}
}| Property | Type | Required | Description |
|---|---|---|---|
client_sdk.platform |
enum | Accepted values are ios, android, web, tvos, roku, alexa, smart_tv, fire, xbox, and other. |
|
context |
string | An encoded string representing the result of the previous request. This is available in the Response body. | |
environment |
enum | Required | Either production or development. |
request_id |
string | A UUID for the request. | |
request_timestamp_ms |
integer | Unix timestamp for the request. | |
previous_mpid |
string | The mParticle ID returned by the previous request. | |
known_identities |
object | Required | An object containing all available identifiers for a user, to be used by mParticle to match and return a user profile. This object must include at least one identifier. See the example for a full list of allowed identifiers. |
The identify, search, login, and logout return a body with the following schema:
{
"context": "string",
"mpid": "string",
"matched_identities": {
"ios_idfa": "string",
"android_aaid": "string",
"amp_id": "string",
"android_uuid": "string",
"ios_idfv": "string",
"push_token": "string",
"roku_publisher_id": "string",
"roku_aid": "string",
"fire_aid": "string",
"customerid": "string",
"email": "string",
"facebook": "string",
"facebookcustomaudienceid": "string",
"google": "string",
"microsoft": "string",
"other": "string",
"twitter": "string",
"yahoo": "string",
"device_application_stamp": "string"
},
"is_ephemeral": true
}| Property | Type | Description |
|---|---|---|
context |
string | Encoded version of the response, may be used as the context parameter in the next request |
mpid |
string | The mParticle ID of the matched user profile |
matched_identities |
object | Each identifier from the known_identities object in the request body that matched to an identifier in the returned user profile. N.B - only identifiers which were matched from your request will be returned. This is not a complete list of all identities associated with the user profile. |
is_ephemeral |
bool | The returned identity can be removed from local storage when you transition to the next identity |
/searchThe search path should be used when you wish to determine the existence of a user identity. It is similar to identify in that it accepts a set of known identities and returns an mParticle ID. You should provide all available identifying information for the given user. However, the search path is different from identify in that if there are no matches, it will not create a new mParticle ID, it will return a user not found error message.
The search endpoint takes the same request and response objects as the Identify request.
/login and /logoutThese paths should be used when you wish to transition user states in your app. For example, you may use /login to transition from your initial state with an anonymous user, to a logged in state with a known user. Just as with /identify, these paths accept a set of known identities and return an mParticle ID, in accordance with an Identity Strategy. You should provide all available identifying information for the given user.
For both /login and /logout, the known_identities object should refer to the user profile you wish to transition to. For logout, this may mean that you only include a device id or a device_application_stamp that you generate to associate with the unauthenticated user/device.
The login, and logout endpoints take the same request and response objects as the Identify request.
/{mParticle ID}/modifyModify must be performed on an existing mParticle ID. It will mutate an existing user, and will never result in a new user. Use the JSON null sentinel to convey the addition or removal of an ID:
{
"client_sdk": {
"platform": "ios",
"sdk_vendor": "string",
"sdk_version": "string"
},
"environment": "production",
"request_id": "string",
"request_timestamp_ms": 0,
"identity_changes": [
{
"old_value": "string",
"new_value": "string",
"identity_type": "ios_idfa"
},
{
"old_value": "string",
"new_value": null,
"identity_type": "ios_idfv"
},
{
"old_value": null,
"new_value": "email@example.com",
"identity_type": "email"
}
]
}| Error | Description |
|---|---|
| 400 Bad Request | See the response body for detailed error message. |
| 401 Unauthorized | Request failed authentication. |
| 429 Too Many Requests | Too many requests have been submitted. To correct, perform an exponential backoff. Learn more about API throttling in Default Service Limits. |
| 5xx Server Error | A server-side error has occured. Try your request again. |
{
"errors": [
{
"code": "string",
"message": "string"
}
]
}Was this page helpful?