ChurnZero

Sync customer data from your warehouse to ChurnZero. Keep your ChurnZero accounts, contacts, and events enriched with the latest attributes from your data warehouse to power customer success workflows.

Prerequisites

• A ChurnZero account with API access enabled
• A ChurnZero Application Key (App Key)
• Your ChurnZero instance URL (if using a regional or custom endpoint)

Authentication

ChurnZero uses an Application Key (App Key) for authentication.

1. In ChurnZero, navigate to Admin > Application Keys
2. Click New App Key to create a new key, or copy an existing one
3. In Zeotap, paste the App Key into the App Key field

The App Key is included with every API request to authenticate your account. Treat it as a secret and do not share it publicly.

Configuration

Target Settings

Object Types

• Account: Sets attributes on ChurnZero accounts using the setAttribute action. Requires accountExternalId.
• Contact: Sets attributes on ChurnZero contacts using the setAttribute action. Requires both accountExternalId and contactExternalId.
• Event: Tracks events in ChurnZero using the trackEvent action. Requires accountExternalId, contactExternalId, and eventName.

Supported Operations

Sync Modes

Audience Sync Modes

ChurnZero does not have a list or segment membership API, so audience sync modes are not supported.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Any additional mapped fields are sent as custom attributes on the account, contact, or event.

How It Works

1. Data extraction: Zeotap reads rows from your configured model or audience.
2. Field mapping: Source columns are mapped to ChurnZero fields using your field mapping configuration.
3. Batching: Rows are grouped into batches of 75 actions per API request.
4. API calls: Each batch is sent as a JSON array via HTTP POST to the ChurnZero /i endpoint.
5. Retry logic: Failed requests are retried with exponential backoff (up to 3 retries) for transient errors (429, 5xx).

API Actions by Object Type

For Account and Contact syncs, every mapped field (except identifiers) is sent as a custom attribute on the setAttribute action. Custom attribute names must exactly match the names configured in ChurnZero Admin.

For Event syncs, the trackEvent action is used with the mapped eventName, eventDate, quantity, and description fields.

Rate Limits

ChurnZero does not publicly document API rate limits. Zeotap uses conservative batch sizes (75 actions per request) and automatic retry with backoff to handle any rate limiting gracefully.

If you experience rate limit errors, contact ChurnZero support to understand your account’s API limits.

Best Practices

• Use consistent external IDs: Ensure that accountExternalId and contactExternalId values match the identifiers already in use in your ChurnZero account.
• Create custom attributes first: Custom attributes must be created in ChurnZero Admin before they can be set via the API. Attributes that do not exist are silently ignored.
• Attribute names are case-sensitive: Custom attribute names in your field mapping must exactly match the names configured in ChurnZero.
• Event dates must be in the past: ChurnZero rejects events with future dates. Ensure your eventDate values are in ISO 8601 format and represent past timestamps.
• Contacts require existing accounts: A contact’s parent account must exist in ChurnZero before the contact can be created or updated.
• Remove trailing slashes from Instance URL: Including a trailing slash in the Instance URL can cause 404 errors.

Troubleshooting

Sync succeeds but data does not appear in ChurnZero

ChurnZero’s API does not return detailed error messages for invalid data. Verify that:

• Your App Key is correct and active
• The accountExternalId matches an existing account (or will create one)
• Custom attribute names exactly match what is configured in ChurnZero Admin (case-sensitive)

Authentication failed: invalid app key

Generate a new App Key in ChurnZero under Admin > Application Keys and update your destination credentials in Zeotap.

HTTP 404 errors

Ensure your Instance URL does not include a trailing slash or the /i path. The correct format is https://analytics.churnzero.net (not https://analytics.churnzero.net/ or https://analytics.churnzero.net/i).

Contact sync fails with missing contactExternalId

When syncing contacts, both accountExternalId and contactExternalId are required. Ensure both fields are mapped in your field mapping configuration.

Event dates rejected

ChurnZero rejects events with dates in the future. Ensure your eventDate column contains valid ISO 8601 timestamps that represent past events.

Custom attributes not updating

Custom attributes must be pre-created in ChurnZero before they can be set via the API. Navigate to Admin > Custom Fields in ChurnZero and create the attributes before running your sync.

Rate limiting errors

If you see HTTP 429 errors, Zeotap will automatically retry with exponential backoff. If errors persist, contact ChurnZero support to understand your API rate limits, or reduce sync frequency.