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 hovering your cursor over the Settings gear icon in the left nav bar, and then clicking Workspaces.
2. 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/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 your mParticle account.
  2. In the left hand nav bar, hover your cursor over the Settings gear icon and click Platform under 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

Response

A successful request receives a 202 Accepted response.

Limits

• 1500 profiles per second
• 100 profiles per request

Profile data that is deleted will become effectively inaccessible but will not be entirely physically 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

There are two optional methods you can use to verify the successful removal of specific user data:

• Verify using Audiences
• Verify 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