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.

Authentication

When using the Bulk Profile Data Deletion API, you must authenticate with Basic Auth using a key and secret from one of your configured inputs.

1. Log into your mParticle account and navigate to Setup > Inputs.
2. Select any of your configured inputs and copy the key and secret. You can then use these as your username and password when authenticating to the Bulk Profile Deletion API. It doesn’t matter which input you select.

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

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.

Your request should always consist of an array of mpid and action pairs as shown in the example above, even if your request contains only a single user profile. Submitting a request containing a single object that is not within an array will result in an error.

Example JSON request body

[
  {
    "mpid": "profile-mpid-1",
    "action": "delete"
  },
  {
    "mpid": "profile-mpid-2",
    "action": "delete"
  },
  {
    "mpid": "profile-mpid-3",
    "action": "delete"
  }
]

Response

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

Limits

• 1500 MPIDs per second
• 100 MPIDs 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-

Tokens cannot be revoked, but they expire every eight hours. The initial token request can take between one and three seconds, so mParticle recommends that you cache the token and refresh it only when necessary.

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