mParticle
Send user data, events, and audience membership to mParticle for customer data routing and activation. Zeotap connects to the mParticle Events API to push warehouse-modeled data into your mParticle workspace.
Prerequisites
- An mParticle account with a workspace configured
- A server-to-server API key and secret (generated in the mParticle UI under Setup > Inputs > Platform Inputs)
- Your mParticle data center region (US1, US2, EU1, or AU1)
Authentication
mParticle uses API Key + Secret authentication via HTTP Basic Auth.
- In mParticle, navigate to Setup > Inputs > Platform Inputs
- Click + Platform and select a platform (e.g., Feeds or Custom Feed)
- Copy the Server to Server Key and Server to Server Secret
- In Zeotap, paste the key into the API Key field and the secret into the API Secret field
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Data Center | Select | Yes | The mParticle data center region: US1 (default), US2, EU1, or AU1 |
| Environment | Select | Yes | The mParticle environment: Production (default) or Development |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Event Type | Select | Yes | The type of data to send: User Attributes (identify), Custom Event, Commerce Event, or Screen View |
Supported Operations
Sync Modes
| Mode | Supported |
|---|---|
| Upsert | Yes |
| Insert | Yes |
| Update | — |
| Mirror | — |
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Upsert | Yes |
| Remove | — |
| Mirror | — |
Features
- Field Mapping: Yes
- Schema Introspection: No
Required Mapping Fields
| Event Type | Required Fields |
|---|---|
| User Attributes | customer_id |
| Custom Event | customer_id, event_name |
| Commerce Event | customer_id, product_action |
| Screen View | customer_id, screen_name |
Default Destination Fields
All Event Types: customer_id, email, mobile_number, phone_number_2
User Attributes: first_name, last_name, age, gender, country, city, zip
Custom Event: event_name, custom_event_type, custom_attributes
Commerce Event: product_action, product_id, product_name, product_price, product_quantity, currency_code, total_amount, transaction_id
Screen View: screen_name, activity_type
How It Works
- Zeotap maps your warehouse columns to mParticle fields using the field mapping you configure
- Each row is converted into an mParticle event batch containing user identities, user attributes, and/or events
- Rows are sent in bulk via the
/v2/bulkeventsendpoint, with up to 100 user batches per request - mParticle uses Basic HTTP authentication with your API key and secret
- Failed requests are retried with exponential backoff and jitter, respecting the
Retry-Afterheader
Identity Resolution
Zeotap maps known identity fields to mParticle’s user_identities object:
| Zeotap Field | mParticle Identity |
|---|---|
| customer_id | customer_id |
| mobile_number | mobile_number |
| phone_number_2 | phone_number_2 |
All other fields are sent as user attributes or event properties depending on the selected event type.
Rate Limits
mParticle enforces rate limits on the Events API:
- Default: ~270 batches per second per workspace
- Request size: Maximum 256 KB per request
- Batch limit: Up to 100 user batches per
/v2/bulkeventsrequest - Events per user: 150 average per 24 hours
When rate limits are exceeded, mParticle returns HTTP 429 with a Retry-After header. Zeotap automatically retries with exponential backoff.
Best Practices
- Use the correct data center — Ensure your selected data center matches your mParticle workspace region. Sending data to the wrong region will result in authentication failures.
- Map identity fields — Always map at least
customer_idto enable mParticle’s identity resolution. Addemailwhen available for richer user profiles. - Prefer User Attributes for profile data — Use the “User Attributes” event type for demographic and profile data. Reserve “Custom Event” for behavioral data.
- Use Production environment for live data — Only use the Development environment for testing. Development data is isolated from production audiences and outputs.
- Keep event names consistent — Use a naming convention for custom events (e.g., snake_case) to avoid duplicate events in mParticle.
Troubleshooting
Authentication failed (401/403)
Verify that your API key and secret are correct and belong to a server-to-server input, not a client-side SDK key. Server keys are found under Setup > Inputs > Platform Inputs in mParticle.
Wrong data center
US1, US2, EU1, and AU1 are separate environments. Data sent to the wrong region will fail authentication. Check your mParticle workspace URL to determine your region.
Events not appearing in mParticle
Ensure the Environment setting matches where you are looking in mParticle. Development events only appear in the Development environment view. Switch to Live Stream in mParticle to see incoming data in real time.
Rate limit exceeded (429)
Zeotap automatically retries on 429 responses. If you see persistent rate limit errors, reduce your sync frequency or contact mParticle to increase your workspace limits.
Missing user attributes
User attributes are only sent when the Event Type is set to User Attributes. If you selected Custom Event or Commerce Event, non-identity fields are sent as event properties, not user attributes.
Commerce events not tracking products
Ensure you map product_action (e.g., purchase, add_to_cart) and at least product_id. The commerce event requires a valid action value from the mParticle product action enum.
Large payloads rejected
mParticle limits request payloads to 256 KB. If your rows contain large JSON fields, consider reducing the number of mapped fields or splitting data across multiple syncs.