User Profiles

Manage user profile data and properties

POST /engage

User Profiles

cURL

curl --request POST \
  --url https://api.mixpanel.com/engage \
  --header 'Content-Type: application/json' \
  --data '
{
  "$token": "<string>",
  "$distinct_id": "<string>",
  "$set": {},
  "$set_once": {},
  "$add": {},
  "$union": {},
  "$append": {},
  "$remove": {},
  "$unset": [
    {}
  ],
  "$delete": "<string>",
  "$ignore_alias": true
}
'

User Profiles

User profiles store persistent information about your users. Use the Engage API to create and update user profiles with various operations.

Base URL

https://api.mixpanel.com/engage

Authentication

User profile updates use your project token for authentication.

Set Property

Set one or more properties on a user profile. Creates the profile if it doesn’t exist, or updates existing properties.

ip · string

If set to 1, uses the request IP for geolocation

strict · string

Enable strict mode for validation

verbose · string

Return detailed response instead of 1 or 0

Request Body

$token · string · required

Your project token

$distinct_id · string · required

The unique identifier for the user

$set · object · required

Object containing property names and values to set

Example

cURL

curl https://api.mixpanel.com/engage \
  --data-urlencode data='[
    {
      "$token": "YOUR_PROJECT_TOKEN",
      "$distinct_id": "user123",
      "$set": {
        "$email": "[e-mail]",
        "$name": "John Doe",
        "plan": "premium",
        "credits": 100
      }
    }
  ]'

---

Set Property Once

Set properties only if they don’t already exist. Useful for properties like “First Login Date” or “Signup Source”.

Request Body

$token · string · required

Your project token

$distinct_id · string · required

The unique identifier for the user

$set_once · object · required

Object containing properties to set only if they don’t exist

Example

cURL

curl https://api.mixpanel.com/engage \
  --data-urlencode data='[
    {
      "$token": "YOUR_PROJECT_TOKEN",
      "$distinct_id": "user123",
      "$set_once": {
        "first_login": "2024-01-15",
        "signup_source": "google_ads",
        "referrer": "friend_user456"
      }
    }
  ]'

---

Increment Numerical Property

Increment or decrement numerical properties. Use negative values to decrement.

Request Body

$token · string · required

Your project token

$distinct_id · string · required

The unique identifier for the user

$add · object · required

Object with property names and numerical values to add. Use negative values to subtract.

Example

cURL

curl https://api.mixpanel.com/engage \
  --data-urlencode data='[
    {
      "$token": "YOUR_PROJECT_TOKEN",
      "$distinct_id": "user123",
      "$add": {
        "login_count": 1,
        "credits": 50,
        "failed_attempts": -1
      }
    }
  ]'

If the property doesn’t exist, it will be created and set to the specified value (adding to 0).

---

Union To List Property

Add values to a list property, ensuring each value appears only once.

Request Body

$token · string · required

Your project token

$distinct_id · string · required

The unique identifier for the user

$union · object · required

Object with property names and arrays of values to add

Example

cURL

curl https://api.mixpanel.com/engage \
  --data-urlencode data='[
    {
      "$token": "YOUR_PROJECT_TOKEN",
      "$distinct_id": "user123",
      "$union": {
        "favorite_genres": ["action", "comedy"],
        "visited_pages": ["homepage", "pricing"],
        "used_features": ["export", "analytics"]
      }
    }
  ]'

---

Append to List Property

Append values to a list property. Unlike union, this allows duplicate values.

Request Body

$token · string · required

Your project token

$distinct_id · string · required

The unique identifier for the user

$append · object · required

Object with property names and values to append

Example

cURL

curl https://api.mixpanel.com/engage \
  --data-urlencode data='[
    {
      "$token": "YOUR_PROJECT_TOKEN",
      "$distinct_id": "user123",
      "$append": {
        "purchase_history": {"item": "Premium Plan", "date": "2024-01-15"},
        "activity_log": "Logged in from mobile"
      }
    }
  ]'

---

Remove from List Property

Remove specific values from a list property.

Request Body

$token · string · required

Your project token

$distinct_id · string · required

The unique identifier for the user

$remove · object · required

Object with property names and values to remove

Example

cURL

curl https://api.mixpanel.com/engage \
  --data-urlencode data='[
    {
      "$token": "YOUR_PROJECT_TOKEN",
      "$distinct_id": "user123",
      "$remove": {
        "favorite_genres": "horror",
        "interests": "deprecated_feature"
      }
    }
  ]'

---

Delete Property

Permanently remove properties from a user profile.

Request Body

$token · string · required

Your project token

$distinct_id · string · required

The unique identifier for the user

$unset · array · required

Array of property names to delete

Example

cURL

curl https://api.mixpanel.com/engage \
  --data-urlencode data='[
    {
      "$token": "YOUR_PROJECT_TOKEN",
      "$distinct_id": "user123",
      "$unset": ["temp_token", "session_id", "cache_data"]
    }
  ]'

---

Delete Profile

Permanently delete a user profile and all its properties.

Request Body

$token · string · required

Your project token

$distinct_id · string · required

The unique identifier for the user

$delete · string · required

Set to empty string or null (value is ignored)

$ignore_alias · boolean

Set to true to delete only this specific distinct_id without following alias chains

Example

cURL

curl https://api.mixpanel.com/engage \
  --data-urlencode data='[
    {
      "$token": "YOUR_PROJECT_TOKEN",
      "$distinct_id": "user123",
      "$delete": "",
      "$ignore_alias": false
    }
  ]'

Deleting a profile is permanent and cannot be undone. Use with caution.

---

Batch Update

Send multiple profile updates in a single request. You can mix different operations.

Example

Python

data = [
    {
        "$token": "YOUR_PROJECT_TOKEN",
        "$distinct_id": "user123",
        "$set": {"$email": "[e-mail]"}
    },
    {
        "$token": "YOUR_PROJECT_TOKEN",
        "$distinct_id": "user456",
        "$add": {"login_count": 1}
    },
    {
        "$token": "YOUR_PROJECT_TOKEN",
        "$distinct_id": "user789",
        "$unset": ["temp_data"]
    }
]

response = requests.post(
    'https://api.mixpanel.com/engage',
    data={'data': json.dumps(data)}
)

Reserved Properties

Mixpanel reserves certain property names (prefixed with $) for special purposes:

Property	Description
$email	User’s email address
$name	User’s full name
$first_name	User’s first name
$last_name	User’s last name
$phone	User’s phone number
$avatar	URL to user’s avatar image
$created	Profile creation time (set automatically)
$last_seen	Last activity time (set automatically)

You can use custom properties alongside reserved properties. Just avoid using the $ prefix for your custom properties.

Best Practices

Use $set_once for immutable properties

Properties like signup date or first referrer should use $set_once to prevent overwriting:

"$set_once": {
    "signup_date": "2024-01-15",
    "first_referrer": "google.com"
}

Batch profile updates

Update multiple profiles in a single request for better performance:

updates = []
for user in users:
    updates.append(create_profile_update(user))

# Send in batches of 2000

Use appropriate data types

• Numbers for metrics: "credits": 100
• Strings for categories: "plan": "premium"
• Lists for collections: "interests": ["tech", "gaming"]
• ISO dates for timestamps: "last_purchase": "2024-01-15T10:30:00Z"

Keep list properties manageable

Avoid storing thousands of items in list properties. Consider:

• Using counts instead of full lists
• Storing only recent items
• Moving historical data to events