Documentation

Developers

API References
Data Subject Request API

Data Subject Request API Version 1 and 2

Data Subject Request API Version 3

Platform API

Platform API Overview

Accounts

Apps

Audiences

Calculated Attributes

Data Points

Feeds

Field Transformations

Services

Users

Workspaces

Warehouse Sync API

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

Custom Access Roles API

Bulk Profile Deletion API Reference

Data Planning API

Group Identity API Reference

Calculated Attributes Seeding API

Pixel Service

Profile API

Events API

mParticle JSON Schema Reference

IDSync

Client SDKs
AMP

AMP SDK

Android

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

Cordova Plugin

Identity

Direct Url Routing

Direct URL Routing FAQ

Web

Android

iOS

Flutter

Getting Started

Usage

API Reference

iOS

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

React Native

Getting Started

Identity

Roku

Getting Started

Identity

Media

Unity

Upload Frequency

Getting Started

Opt Out

Initialize the SDK

Event Tracking

Commerce Tracking

Error Tracking

Screen Tracking

Identity

Location Tracking

Session Management

Xbox

Getting Started

Identity

Web

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

Xamarin

Getting Started

Identity

Web

Alexa

Media SDKs

iOS

Web

Android

Quickstart
Android

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

HTTP Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

iOS Quick Start

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

Java Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

Node Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

Python Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

Web

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

Server SDKs

Node SDK

Go SDK

Python SDK

Ruby SDK

Java SDK

Tools

mParticle Command Line Interface

Linting Tools

Smartype

Guides
Partners

Introduction

Outbound Integrations

Outbound Integrations

Firehose Java SDK

Inbound Integrations

Kit Integrations

Overview

Android Kit Integration

JavaScript Kit Integration

iOS Kit Integration

Compose ID

Data Hosting Locations

Glossary

Migrate from Segment to mParticle

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

Guides

Getting Started

Create an Input

Start capturing data

Connect an Event Output

Create an Audience

Connect an Audience Output

Transform and Enhance Your Data

Platform Guide
The New mParticle Experience

The new mParticle Experience

The Overview Map

Observability

Observability Overview

Observability User Guide

Observability Span Glossary

Introduction

Data Retention

Connections

Activity

Live Stream

Data Filter

Rules

Tiered Events

mParticle Users and Roles

Analytics Free Trial

Troubleshooting mParticle

Usage metering for value-based pricing (VBP)

Analytics

Introduction

Setup

Sync and Activate Analytics User Segments in mParticle

User Segment Activation

Welcome Page Announcements

Settings

Project Settings

Roles and Teammates

Organization Settings

Global Project Filters

Portfolio Analytics

Analytics Data Manager

Analytics Data Manager Overview

Events

Event Properties

User Properties

Revenue Mapping

Export Data

UTM Guide

Query Builder

Data Dictionary

Query Builder Overview

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

Understanding the Screen View Event

Analyses

Analyses Introduction

Segmentation: Basics

Getting Started

Visualization Options

For Clauses

Date Range and Time Settings

Calculator

Numerical Settings

Segmentation: Advanced

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

Funnels: Basics

Getting Started with Funnels

Group By Settings

Conversion Window

Tracking Properties

Date Range and Time Settings

Visualization Options

Interpreting a Funnel Analysis

Funnels: Advanced

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

Cohorts

Getting Started with Cohorts

Analysis Modes

Save a Cohort Analysis

Export Results

Explore Users

Saved Analyses

Manage Analyses in Dashboards

Journeys

Getting Started

Event Menu

Visualization

Ending Event

Save a Journey Analysis

Users

Getting Started

User Activity Timelines

Time Settings

Export Results

Save A User Analysis

Dashboards

Dashboards––Getting Started

Manage Dashboards

Dashboard Filters

Organize Dashboards

Scheduled Reports

Favorites

Time and Interval Settings in Dashboards

Query Notes in Dashboards

User Aliasing

Analytics Resources

The Demo Environment

Keyboard Shortcuts

Tutorials

Analytics for Marketers

Analytics for Product Managers

Compare Conversion Across Acquisition Sources

Analyze Product Feature Usage

Identify Points of User Friction

Time-based Subscription Analysis

Dashboard Tips and Tricks

Understand Product Stickiness

Optimize User Flow with A/B Testing

User Segments

APIs

User Segments Export API

Dashboard Filter API

IDSync

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

Data Master
Group Identity

Overview

Create and Manage Group Definitions

Introduction

Catalog

Live Stream

Data Plans

Data Plans

Blocked Data Backfill Guide

Personalization
Predictive Attributes

Predictive Attributes Overview

Create Predictive Attributes

Assess and Troubleshoot Predictions

Use Predictive Attributes in Campaigns

Predictive Audiences

Predictive Audiences Overview

Using Predictive Audiences

Introduction

Profiles

Calculated Attributes

Calculated Attributes Overview

Using Calculated Attributes

Create with AI Assistance

Calculated Attributes Reference

Audiences

Audiences Overview

Real-time Audiences

Standard Audiences

Journeys

Journeys Overview

Manage Journeys

Download an audience from a journey

Audience A/B testing from a journey

Journeys 2.0

Warehouse Sync

Data Privacy Controls

Data Subject Requests

Default Service Limits

Feeds

Cross-Account Audience Sharing

Approved Sub-Processors

Import Data with CSV Files

Import Data with CSV Files

CSV File Reference

Glossary

Video Index

Analytics (Deprecated)
Identity Providers

Single Sign-On (SSO)

Setup Examples

Settings

Debug Console

Data Warehouse Delay Alerting

Introduction

Developer Docs

Introduction

Integrations

Introduction

Rudderstack

Google Tag Manager

Segment

Data Warehouses and Data Lakes

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

Snowflake (Snowplow Schema)

Snowplow Schema Overview

Snowflake (Define Your Own Schema)

APIs

Dashboard Filter API (Deprecated)

REST API

User Segments Export API (Deprecated)

SDKs

SDKs Introduction

React Native

iOS

Android

Java

JavaScript

Python

Object API

Developer Basics

Aliasing

Bulk Profile Deletion API Reference

The Bulk Profile Deletion API allows you to programatically remove customer profiles, helping to improve your data quality and maintain your compliance with privacy requirements. This API-first approach to profile deletion allows you to automate an often complex and time-consuming process.

By removing erroneous or unnecessary profiles in bulk, you can resolve data integrity problems that propagated from a small error or bug in your code.

The Bulk Profile Deletion API should not be confused with the Data Subject Requests (DSR) API. There are several critical differences:

  • Only the DSR API can be used to fulfill a request originating from a customer to delete a profile, because the DSR API complies with governmental regulations like the GDPR and CCPA. For example, (as required by the GDPR and CCPA) DSR API requests incur a default waiting period of 14 days. In other words, deletion requests are not fulfilled immediately to give customers the opportunity to revoke their request. Additionally, the DSR API executes a physical deletion of user data as opposed to the Bulk Profile Deletion API, which only executes a logical deletion.
  • The Bulk Profile Deletion API is designed to remove user profiles quickly and in large quantities. To make this possible, the Bulk Profile Deletion API does not comply with GDPR and CCPA requirements when fulfilling customer initiated profile deletion requests.

Profile deletion and identity scope

Profiles removed using the Bulk Profile Deletion API are always removed within the scope of a single workspace. For example, if a profile exists in two workspaces A and B in the same account, and the Profile Deletion API is used to remove the profile in workspace A, it will still exist in workspace B.

To remove the profile from both workspaces, you must make the same deletion request twice, once for each workspace, using two sets of credentials: one scoped for workspace A and another scoped for workspace B.

When verifying the deletion of a profile using the methods described below, you will see different results depending on your identity scope settings:

Continuing with the example above, if both workspaces A and B have the same identity scope:

  • The same identifiers included with events sent to both workspaces will all resolve to the same profile with the same MPID in both workspaces.
  • After deleting the profile from workspace A, the profile will still appear in the User Activity View in both workspaces, but it will only belong to workspace B.

However, if workspace A and B have different identity scopes:

  • The same identifiers included with events sent to both workspaces will resolve to two different profiles, with a unique MPID in each workspace.
  • After deleting the profile from workspace A, the profile will no longer appear in the User Activity View in workspace A.

This is because the User Activity View filters profiles to display based account and identity scope. Learn more about how data is organized in mParticle in Accounts, organizations, and workspaces.

Authentication

You must authenticate requests to the Bulk Profile Data Deletion API using basic authentication with a workspace key and secret.

To obtain a Workspace key and secret:

  1. Log into your mParticle account, and navigate to the Workspace Settings page by clicking your workspace name in the left nav bar, and then clicking Settings.
  2. In the list of workspaces, select the workspace where you want to delete profiles.
  3. Expand the Workspace Key/Secret section, and copy the Workspace Key and Secret to use as your username and password for the Basic Auth connection.

    • If necessary, click the Issue Key/Secret button to generate your Workspace credentials.

Delete multiple users

POST <base_url>/userprofile/experimental/bulkdelete

The base URL is specific to the pod location your account is hosted in. Replace <base_url> with the appropriate URL:

  • US1: https://s2s.mparticle.com
  • US2: https://s2s.us2.mparticle.com
  • EU1: https://s2s.eu1.mparticle.com
  • AU1: https://s2s.au1.mparticle.com

You can use either MPIDs (mParticle IDs) or unique identities to specify profiles to delete in your request body.

  • mParticle MPIDs are 64-bit signed integers. Some languages, such as Javascript, do not support these and will truncate. We suggest storing and sending these as strings to avoid truncation or rounding.
  • Unique identifiers are any user identifiers that have been configured to be unique to a profile. To see which identities are set as unique identities in your account:

    1. Log into mParticle your mParticle account.
    2. Click the user profile icon in bottom of the left nav bar, and click Settings.
    3. Select the Identity Settings tab, and look in the Identity Scopes table to view which identity types are assigned as unique identities.

Your request should contain an array of one or more objects where each object represents a deletion request for a single profile. Even a single deletion request object should be contained within an array.

Example JSON request body

[
  {
    "environment_type": "production",
    "action": "delete",
    "mpid": "valid-mpid-id",
    "identities": {
      // Unique identities should be added here if no MPID is given
    }
  },
  {
    "environment_type": "production",
    "action": "delete",
    // If no MPID is given, unique identities should be added in the identities object below
    "identities": {
      "customerid": "valid-customer-id"
    }
  }
]

Request body fields

Field Name Data Type Required Description
environment_type string Required The mParticle environment type for the profiles you want to delete. Valid values are production or development.
action string Required The action to perform on the profiles. Valid value is delete.
identities JSON object Required if no MPID is given A JSON object containing a list of key/value pairs where the key the unique identity type (like customerid or email) and the value is the unique identity for the profile to delete.
mpid integer Required if no identities are given A 64-bit signed integer used to uniquely identify a user profile to delete. The MPID must be added directly to the JSON object for each deletion request, not within the identities object.

Response

A successful request receives a 202 Accepted response. To positively verify your request, follow the steps in Verify the deletion request.

Limits

  • 1500 profiles per second
  • 100 profiles per request

Beta limitations

While the Bulk Profile Deletion API is a Beta release, profile data is not deleted from mParticle’s underlying event store. To remove user data from the event store, you can either:

  • Ask your mParticle account representative to reset your event storage window to a value near zero, which effectively erases your historical stored events, and all included user data.
  • Ask your mParticle account representative to delete a section of your event store corresponding to the period of time erroneous data was logged. However, this requires that erroneous data was sent only within the specified time period.

Verify the deletion request

After submitting your request, you can positively verify the successful removal of specific user data with two methods:

  • Verification using Audiences
  • Verification using the Profile API

Verify using Audiences

  1. Before submitting a deletion request, find or create an audience containing all the users you want to delete.
  2. After submitting the deletion request, create a new audience with the same selection criteria used with your first audience. If your deletion request was successful, none of the deleted user profiles will appear in the new audience.

For example, assume invalid data was sent to a set of profiles between February 1st and February 10th, and you need to delete the now compromised profiles:

  1. Create a new audience constrained to users first seen between February 1 and February 10.
  2. Submit a profile deletion request for the same set of users.
  3. If the deletion request was successful, a new audience constrained to users first seen between Feb 1 and Feb 10 will be empty.

Verify using the Profile API

Since the Profile API can retrieve user profiles from mParticle, it can also be used to verify the removal of specific profiles.

  1. Create a set of API credentials for the Profile API as described in Authentication.
  2. Create a bearer token by sending a POST request to mParticle’s SSO token endpoint at https://sso.auth.mparticle.com/oauth/token.

The JSON body of the request must contain:

  • client_id - the client ID, issued by mParticle when creating the API credentials
  • client_secret - the client secret, issued by mParticle when creating the API credentials
  • audience - set to a value of "https://api.mparticle.com"
  • grant_type - set to a value of "client_credentials"

Example cURL request

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

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

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

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

Your request to the Profile API can be authorized by setting the authorization header to:

Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-

  1. Submit a GET request to /userprofile/v1/<orgId>/<accountId>/<workspaceId>/<mpid>, using the organization ID, account ID, workspace ID, and MPID for the profile you removed.
  2. If your deletion request was successful, you will receive an error stating that the MPID provided could not be found, indicating the successful removal. If your deletion request failed, you will receive the profile information in a JSON object.

Error handling

Response code Error message Description
400 Bad Request - malformed JSON or required field missing The JSON in your request body could be invalid or it could include a syntax error. Use a JSON linter to verify your JSON formatting, and make sure your request contains a single array of multiple objects, each with an mpid and action field. It is also possible you included an MPID within the identities object for a deletion request; MPIDs cannot be included within the identities object. The error message specifies any required fields that are missing.
401 Unauthorized - authentication missing or invalid Make sure your API credentials include the Bulk Profile Deletion API, your authorization header is formatted correctly, and that the API key/secret included are correct or that your bearer token is correct.
403 Forbidden - API key/secret are present but not valid Make sure that the API credentials used to generate your API key/secret or your bearer token include the Bulk Profile Deletion API.
429 Too many requests - rate limiting is being applied Your request either contains too many MPIDs or you have submitted too many requests. Make sure you request to delete no more than 1500 MPIDs per second, and that each individual request contains no more than 100 MPIDs
503 Service unavailable - the message should be retried after a back off After exponentially backing off your requests, retry. If you continue to encounter this error, contact mParticle Support.

Was this page helpful?

    Last Updated: November 20, 2024