CleverTap

Mobile-first customer engagement and retention platform. Sync user profiles and events from your warehouse to CleverTap via their Server API.

Prerequisites

• A CleverTap account
• Your CleverTap Account ID and Passcode (found in Settings > Project)
• Your CleverTap data center region

Authentication

CleverTap uses Account ID + Passcode authentication.

1. In CleverTap, navigate to Settings > Project
2. Copy your Account ID (also called Project ID)
3. Copy your Passcode
4. In Zeotap, paste the Account ID and Passcode into the corresponding fields

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

CleverTap does not have a list or segment membership API, so audience sync modes are not supported. Use regular sync modes to push profile or event data.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

The identity field is the primary user identifier in CleverTap. It can be an email address, phone number, or custom string ID. New profiles are automatically created if the identity does not yet exist.

Default Destination Fields

User Profiles

identity, Name, Email, Phone, Gender, DOB, MSG-email, MSG-push, MSG-sms, MSG-whatsapp

Events

identity, evtName, ts

Any additional mapped fields for profiles are stored as custom profile properties. For events, additional fields are stored as event properties (evtData).

How It Works

1. Zeotap reads rows from your model or audience query
2. Rows are transformed according to your field mappings
3. Records are batched into groups of up to 1,000 per API call
4. Each batch is sent to the CleverTap POST /1/upload endpoint
5. CleverTap returns per-record success/failure status
6. Zeotap retries transient failures (HTTP 429, 5xx) with exponential backoff

Profile Uploads

Each row is sent as a record with "type": "profile". The identity field is placed at the top level, and all other mapped fields are nested inside a profileData object. CleverTap automatically creates new profiles or updates existing ones based on the identity value.

Event Uploads

Each row is sent as a record with "type": "event". The identity, evtName, and ts fields are placed at the top level, and all other mapped fields are nested inside an evtData object. If ts is not provided, CleverTap uses the current server timestamp.

Rate Limits

• Concurrent requests: 15 per account (HTTP 429 returned when exceeded)
• Batch size: Up to 1,000 records per API call
• Attribute key length: Maximum 120 bytes
• Attribute value length: Maximum 512 bytes
• Custom profile properties: Maximum 256 per profile
• Event types: Maximum 512 per account
• Event properties: Maximum 256 per event type

Zeotap automatically handles rate limiting with retry and exponential backoff.

Best Practices

• Use a consistent identity: Pick one identity scheme (email, phone, or custom ID) and use it consistently across all syncs to avoid creating duplicate profiles.
• Keep event names concise: CleverTap limits accounts to 512 event types. Use a controlled vocabulary for event names.
• Use the correct region: Selecting the wrong data center region causes authentication failures. Check your CleverTap dashboard URL to determine your region.
• Prefer upsert mode: For profile syncs, upsert ensures that both new and existing profiles are handled correctly.
• Include timestamps for events: Map a timestamp column to the ts field for accurate event ordering. Without it, CleverTap uses server receipt time.

Troubleshooting

Authentication failed: invalid Account ID or Passcode

Verify your Account ID and Passcode in CleverTap under Settings > Project. Ensure you are using the correct project credentials, not a personal API token.

Wrong data center region

Each CleverTap account is hosted in a specific data center. If you see authentication errors despite correct credentials, verify your region by checking your CleverTap dashboard URL (e.g., us1.dashboard.clevertap.com means United States).

Identity field missing

Every record sent to CleverTap requires an identity. Ensure your field mapping includes a source column mapped to the identity destination field. Without it, records are rejected.

Event name missing

Event uploads require an evtName field. Ensure your field mapping includes a source column mapped to evtName for event syncs.

Records appearing in unprocessed array

The CleverTap API response includes an unprocessed array with records that failed validation. Common causes include missing identity, invalid field types, or exceeding the 512-byte value limit. Check the sync run logs in Zeotap for per-record error details.

Rate limit exceeded (HTTP 429)

CleverTap limits concurrent API requests to 15 per account. If multiple syncs run simultaneously, they may exceed this limit. Zeotap retries automatically with backoff, but consider staggering sync schedules if this occurs frequently.

Profile properties not appearing

Custom profile properties may take a few minutes to appear in the CleverTap dashboard after upload. If properties still do not appear, verify that the property key is under 120 bytes and the value is under 512 bytes.

Timestamp format for events

The ts field expects a UNIX epoch timestamp in seconds (e.g., 1468308340), not milliseconds. If your source column uses milliseconds, apply a transformation to divide by 1,000 before mapping.