Batch

Sync user profiles, events, and audience segments to Batch for push notifications, in-app messaging, email, and SMS engagement campaigns. Zeotap keeps your Batch profiles and audiences in sync with your warehouse data.

Prerequisites

A Batch account with API access enabled
A Batch REST API key (found in Settings > General)
Your Batch project key (found in Settings > General)

Authentication

Batch uses REST API Key authentication.

Log in to your Batch dashboard
Navigate to Settings > General
Locate your REST API Key (also called Live REST API Key)
Copy the key and paste it into the REST API Key field in Zeotap
Copy your Project Key from the same settings page

Configuration

Field	Type	Required	Description
Project Key	Text	Yes	Your Batch project key, sent as the `X-Batch-Project` header. Found in Settings > General in the Batch dashboard.

Target Settings

Field	Type	Required	Description
Object Type	Select	Yes	The type of data to send: Profiles (user attributes) or Events (custom events).
Audience Name	Text	No	The name of the Batch audience to sync members to. Required for audience sync modes. Must contain only letters, numbers, hyphens, and underscores.

Supported Operations

Sync Modes

Mode	Supported	Description
Upsert	Yes	Create or update user profiles and attributes (Batch profile updates are idempotent upserts by `custom_id`)
Update	—	Not supported (Batch profile API is upsert-only; use Upsert)
Insert	—	Not supported
Mirror	—	Not supported (no profile delete API)

Audience Sync Modes

Mode	Supported	Description
Add	Yes	Add users to a Batch audience
Remove	Yes	Remove users from a Batch audience
Mirror	Yes	Sync audience membership — add new members and remove those no longer in the segment
Upsert	Yes	Add users to a Batch audience (idempotent)

Features

Field Mapping: Yes
Schema Introspection: No

Required Mapping Fields

Required fields depend on the selected Object Type:

Object Type	Required Fields	Description
Profiles	`custom_id`	Unique user identifier in Batch
Events	`custom_id`, `event_name`	User identifier and the event name to track

Default Destination Fields

Profiles

Field	Type	Description
`custom_id`	string	Unique user identifier
`$email_address`	string	User email address
`$phone_number`	string	Phone number in E.164 format
`$email_marketing`	string	Email marketing opt-in status (`subscribed` or `unsubscribed`)
`$sms_marketing`	string	SMS marketing opt-in status (`subscribed` or `unsubscribed`)
`$language`	string	BCP 47 language tag (e.g., `en`, `fr`)
`$region`	string	ISO 3166-1 alpha-2 country code (e.g., `US`, `FR`)
`$timezone`	string	IANA timezone identifier (e.g., `Europe/Paris`)

Events

Field	Type	Description
`custom_id`	string	Unique user identifier
`event_name`	string	Name of the event (lowercase, alphanumeric and underscores, max 30 chars)

How It Works

Profile Updates

Zeotap sends profile data to the Batch CEP Profiles API (POST /2.9/profiles/update). Each request can contain up to 200 profile objects. Profiles are identified by custom_id and can include both native attributes (prefixed with $) and custom attributes.

Event Tracking

Events are sent via the same Profiles API endpoint, embedded in the events array of each profile update. Each event includes a name, optional timestamp, and custom attributes.

Audience Syncs

When an Audience Name is configured, Zeotap uses the Batch Audiences API (POST /2.9/audiences/update) to manage segment membership. Each request can contain up to 10,000 user IDs. Users are added or removed based on the selected audience sync mode.

Rate Limits

Batch enforces rate limits using a token bucket algorithm:

Profile updates: Up to 300 updates per second with a burst capacity of 1,000
Audience updates: Subject to API rate limits (HTTP 429 responses)

Zeotap handles rate limiting automatically with exponential backoff and retry logic. One “update” in Batch’s rate limit counts per Custom ID, not per API request.

Best Practices

Use custom_id values that are stable and unique across your user base (e.g., internal user IDs, not email addresses)
For native attributes like $email_address and $phone_number, ensure values match the expected format (valid email, E.164 phone format)
Event names must be lowercase with only letters, numbers, and underscores (max 30 characters)
When using audience syncs, create the audience in Batch first — Zeotap does not auto-create audiences. The audience_name must match an existing audience in your Batch project
Custom attribute keys must be lowercase with only letters, numbers, and underscores (max 30 characters)

Troubleshooting

Authentication failed: invalid REST API key

Verify your REST API key in Settings > General in the Batch dashboard. Ensure you are using the Live REST API Key, not the Dev key.

Authorization failed: check project key permissions

The project key may be invalid or may not have the necessary permissions. Verify the project key in Settings > General and ensure it matches the project you want to sync to.

Missing custom_id

Every profile update and event requires a custom_id to identify the user. Ensure your model includes a column mapped to the custom_id field.

Rate limit exceeded (HTTP 429)

Batch limits profile updates to 300 per second. Zeotap handles retries automatically, but if you see persistent rate limit errors, consider reducing sync frequency or batch sizes.

Invalid attribute format

Custom attribute keys must be lowercase, contain only letters, numbers, and underscores, and be no longer than 30 characters. Native attributes (prefixed with $) must match their expected formats — for example, $phone_number must be in E.164 format.

Audience update failed

Ensure the audience name contains only letters, numbers, hyphens, and underscores. The audience must already exist in your Batch project — create it in the Batch dashboard under Audiences before running the sync.