Profile API

The Profile API can be used to query identities, user attributes, audience memberships, and other data available on an mParticle User Profile, anywhere you can make an HTTP request. Profile API can be used to drive one-to-one personalized experiences for your users across any channel:

• Deliver customized product or content recommendations
• Identify churn-risk customers in an automated voice support flow and launch a win-back campaign.
• Deliver personalized offers in brick and mortar stores by integrating your point-of-sale systems.

Base URL

The base URL for the Profile API is https://api.mparticle.com.

Authentication

The Profile API is authenticated with a bearer token. To create a bearer token, first create a set of API credentials in the UI.

Create your API credentials

1. Log in to your mParticle account.
2. Click the User Profile icon at the bottom of the left nav bar, click Settings, and select the API Credentials tab.
3. Click + Add Credential.
4. Enter a descriptive name for the Display name.
5. Check the box next to Profile API, and then expand the available workspaces by clicking the + button. Check the box next to each workspace you need to access user profile data for.
6. Click Save, and copy the Client ID and Client Secret displayed in the modal window before clicking Done.

Create a bearer token

To create a bearer token, send 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":"your-client-id","client_secret":"your-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"
}

Using your bearer token

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

Subsequent requests to the API can then be authorized by setting the authorization header to:

Authorization: Bearer YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-

Rate limits

mParticle imposes default service limits on the Profile API. For the specific limits on retrieving user profiles using the Profile API, see Default Service Limits.

Best practices

Do not submit client-side queries to Profile API from your application’s frontend. Instead, maximize performance in your app by creating a backend personalization service to submit these queries, acting as an intermediary between your app and the mParticle Profile API. This service can be built directly into your app’s existing backend framework, or it can an independent service.

As an example workflow:

1. Your app’s client requests user information (like product recommendations) from your personalization service by providing an identifier for the current user.
2. Your personalization service queries the Profile API using the supplied identifier. Based on information in the returned profile, your personalization service determines the best behavior for your app.
3. Your personalization service send only the information necessary to implement the desired personalization to your app’s frontend. For example, an array of product recommendations.

A simple example personalization service implemented with Node and Express is available on GitHub.

Manage user profiles

Get a profile by mParticle ID

GET /userprofile/v1/{orgID}/{accountId}/{workspaceId}/{mpid}?fields=device_identities,user_identities,user_attributes,audience_memberships,attribution

Path parameters

Query parameters

List of supported fields that can be returned with a user profile:

• device_identities
• user_identities
• user_attributes (includes any calculated attributes)
• audience_memberships
• attribution

Example curl request

curl \
  -X GET \
  -H "Authorization: Bearer {accessToken}" \
  "https://api.mparticle.com/userprofile/v1/{orgId}/{accountId}/{workspaceId}/{mpid}?fields=device_identities,user_identities,user_attributes,audience_memberships,attribution"

Example JSON request body

No request body.

Response

A successful request receives a 200 response with a JSON object for the user profile.

{
  "mpid": 9080350317581165000,
  "created_timestamp_ms": 1574704283462,
  "last_stored_timestamp_ms": 1575301484215,
  "is_opted_out": false,
  "limit_ad_tracking": null,
  "device_identities": [
    {
      "type": "android_id",
      "encoding": "none",
      "value": "8789c459016a94b0"
    },
    {
      "type": "unknown",
      "encoding": "none",
      "value": "0c48aafbd6c69b3e1921fab5ccb528397eb1000854db2b99b1efc8507884b07a"
    },
    {
      "type": "google_advertising_id",
      "encoding": "none",
      "value": "481c8a31-7d5d-4d96-93a0-2de7427167fc"
    },
    {
      "type": "unknown",
      "encoding": "none",
      "value": "1b4469f3fb1f7bee7ba6705d1ce4b9d8a23e76592c34aa6c4a4eea3d0a07aa64"
    }
  ],
  "user_identities": [
    {
      "type": "customer_id",
      "encoding": "none",
      "value": "Example-Customer-mxr15"
    },
    {
      "type": "email",
      "encoding": "none",
      "value": "Example-Customer-mxr15@example.com"
    }
  ],
  "account_user_attributes": null,
  "user_attributes": {
    "ml_product_recs": [
      "123849",
      "294933",
      "937592",
      "500422"
    ],
    "view_preference": "Dark Mode",
    "tp_age": "18-34",
    "tp_gender": "male",
    "last_purchase_category": "Home Decor",
    "churn_risk_score": "4",
    "ltv": "342.1",
    "$city": "New York",
    "$state": "NY",
    "$country": "USA",
    "$firstname": "Marky",
    "$lastname": "Mark"
  },
  "audience_memberships": [
    {
      "audience_id": 17802,
      "audience_name": "Meret final CA test",
      "expiration_timestamp_ms": null
    },
    {
      "audience_id": 17918,
      "audience_name": "Decor Remarketing",
      "expiration_timestamp_ms": null
    }
  ]
}

Get a profile by immutable ID

GET /userprofile/v1/resolve/{orgId}/{accountId}/{workspaceId}

Allows you to retrieve a profile without the mParticle ID. To use this method, your account must have an immutable identity configured in your identity strategy. An immutable identity is set only once and cannot be changed once it is set. It is usually the Customer ID.

Path parameters

Query parameters

List of supported fields that can be returned with a user profile:

• device_identities
• user_identities
• user_attributes (including any calculated attributes)
• audience memberships
• attribution

Request body parameters

Example curl request

curl \
  -X GET \
  -H "Authorization: Bearer {accessToken}" \
  "https://api.mparticle.com/userprofile/v1/resolve/{orgId}/{accountId}/{workspaceId}?fields=device_identities,user_identities,user_attributes,audience_memberships,attribution" \
  -d "{ \"environment_type\": \"production\", \
    \"identity\": {\"type\": \"customer_id\",\"value\": \"12345\"}}"

Example JSON request body

{
  "environment_type": "production",
  "identity": {
    "type": "customer_id",
    "value": "12345"
  }
}

Response

A successful request receives a 200 response with a JSON object for the user profile.

{
  "mpid": 9080350317581165000,
  "created_timestamp_ms": 1574704283462,
  "last_stored_timestamp_ms": 1575301484215,
  "is_opted_out": false,
  "limit_ad_tracking": null,
  "device_identities": [
    {
      "type": "android_id",
      "encoding": "none",
      "value": "8789c459016a94b0"
    },
    {
      "type": "unknown",
      "encoding": "none",
      "value": "0c48aafbd6c69b3e1921fab5ccb528397eb1000854db2b99b1efc8507884b07a"
    },
    {
      "type": "google_advertising_id",
      "encoding": "none",
      "value": "481c8a31-7d5d-4d96-93a0-2de7427167fc"
    },
    {
      "type": "unknown",
      "encoding": "none",
      "value": "1b4469f3fb1f7bee7ba6705d1ce4b9d8a23e76592c34aa6c4a4eea3d0a07aa64"
    }
  ],
  "user_identities": [
    {
      "type": "customer_id",
      "encoding": "none",
      "value": "Example-Customer-mxr15"
    },
    {
      "type": "email",
      "encoding": "none",
      "value": "Example-Customer-mxr15@example.com"
    }
  ],
  "account_user_attributes": null,
  "user_attributes": {
    "ml_product_recs": [
      "123849",
      "294933",
      "937592",
      "500422"
    ],
    "view_preference": "Dark Mode",
    "tp_age": "18-34",
    "tp_gender": "male",
    "last_purchase_category": "Home Decor",
    "churn_risk_score": "4",
    "ltv": "342.1",
    "$city": "New York",
    "$state": "NY",
    "$country": "USA",
    "$firstname": "Marky",
    "$lastname": "Mark"
  },
  "audience_memberships": [
    {
      "audience_id": 17802,
      "audience_name": "Meret final CA test",
      "expiration_timestamp_ms": null
    },
    {
      "audience_id": 17918,
      "audience_name": "Decor Remarketing",
      "expiration_timestamp_ms": null
    }
  ]
}

Error handling

Profile expiration

User profiles expire and will not be returned by the Profile API if they are not accessed or updated for a period of 90 days. The default 90 day expiration period may be adjusted depending on your contract with mParticle. For more information about your account’s profile expiration period, contact your account representative.

User attributes and input source priority

For a given user, attributes are stored at the workspace level, not the device level.

User attributes are ingested according to the following priority:

1. Calculated attributes
2. Account-level attributes (a premium feature)
3. Custom feed input
4. SDK input
5. Custom CSV
6. Partner data feed (PDF). For example, the Punchh integration is a partner data feed.

Once ingested from a particular source type, subsequent source types for that same data won’t be ingested. For example, once you set a user attribute key value using the Web SDK, you won’t be able to set that same key value from a Custom CSV or partner data feed.