MoEngage

AI-powered customer engagement platform. Sync user profiles, custom attributes, and events from your warehouse to MoEngage via their Data API.

Prerequisites

• A MoEngage account with Data API access enabled
• Your MoEngage Workspace ID and Data API Key (found in Settings > Account > APIs)
• Your MoEngage App ID
• Knowledge of which Data Center (DC-01 through DC-06) your account is hosted on

Authentication

MoEngage uses Basic Authentication with your Workspace ID and Data API Key.

1. In MoEngage, navigate to Settings > Account > APIs
2. Copy your Workspace ID (this is the Basic Auth username)
3. Copy your Data API Key (this is the Basic Auth password)
4. In Zeotap, paste these into the Workspace ID and Data API Key fields

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

MoEngage custom segments are filter-based (not list-based), so audience sync is not supported. Use regular sync modes to push user attributes that MoEngage segments can reference.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

User Attributes

customer_id, email, first_name, last_name, moe_mobile, gender, birthday, city, country

Events

customer_id, action, platform, user_time

How It Works

User Attributes (Track User API)

Zeotap sends each user record individually to the MoEngage Track User API endpoint (POST /v1/customer/{appId}). Each request contains the customer ID and an attributes object with all mapped fields. MoEngage creates the user if they don’t exist, or updates their attributes if they do.

Example payload:

{
  "type": "customer",
  "customer_id": "user-123",
  "attributes": {
    "email": "user@example.com",
    "first_name": "Jane",
    "city": "New York"
  }
}

Events (Create Event API)

Each event row is sent individually to the Create Event API (POST /v1/event/{appId}). The action field becomes the event name, and all other mapped fields become event attributes.

Example payload:

{
  "type": "event",
  "customer_id": "user-123",
  "actions": [
    {
      "action": "purchase_completed",
      "attributes": {
        "product": "Shirt",
        "amount": 29.99
      },
      "platform": "web"
    }
  ]
}

Bulk Import (Transition API)

For higher throughput, the Bulk Import mode batches up to 50 user records per API call using the Transition API (POST /v1/transition/{appId}). Each batch must stay under 100KB.

Example payload:

{
  "type": "transition",
  "elements": [
    {
      "type": "customer",
      "customer_id": "user-123",
      "attributes": { "email": "user@example.com" }
    },
    {
      "type": "customer",
      "customer_id": "user-456",
      "attributes": { "email": "other@example.com" }
    }
  ]
}

Rate Limits

MoEngage enforces rate limits on their Data API:

Zeotap handles rate limiting automatically with exponential backoff and retry.

Best Practices

• Use Bulk Import for large syncs — the Bulk Import object type batches multiple records per API call, reducing the number of requests and improving throughput.
• Verify your data center — using the wrong data center will result in authentication failures. Check your MoEngage dashboard URL to confirm.
• Map customer_id consistently — MoEngage uses customer_id as the primary identifier. Ensure it matches across all your syncs to avoid duplicate profiles.
• Use standard attribute names — MoEngage has reserved attribute names like moe_mobile, email, first_name. Using these ensures proper integration with MoEngage’s built-in features.
• Schedule syncs during off-peak hours — to stay within rate limits on large datasets, consider scheduling syncs during periods of lower API usage.

Troubleshooting

Authentication failed: invalid Workspace ID or Data API key

Verify your credentials in MoEngage under Settings > Account > APIs. Ensure you’re using the Data API key (not a different API key type). The Workspace ID is the username, and the Data API Key is the password for Basic Auth.

Wrong data center selected

Each MoEngage data center has a separate API endpoint. If you receive 401 errors despite correct credentials, verify your data center matches your MoEngage dashboard URL (e.g., dashboard-01.moengage.com corresponds to DC-01).

Missing customer_id

Every record sent to MoEngage requires a customer_id. Ensure your model includes a column mapped to this field. If the customer ID is your model’s primary key, Zeotap injects it automatically.

Events not appearing in MoEngage

Verify that the action field is mapped and contains a non-empty value. MoEngage requires an event action name for every event. Also check that the event name matches what you’ve configured in MoEngage’s event schema.

Rate limiting errors

MoEngage enforces ~100 requests per minute on data APIs. For large datasets, use the Bulk Import object type which batches records (up to 50 per request) to reduce API calls. Zeotap automatically retries rate-limited requests with backoff.

Bulk Import payload too large

The Bulk Import API has a 100KB per-request limit. Zeotap chunks records into batches of 50 to stay within this limit. If individual records are very large (many attributes), you may see failures. Consider reducing the number of mapped fields or splitting into multiple syncs.