Cordial

Sync contacts, custom events, orders, and list membership to Cordial for cross-channel marketing automation. Zeotap keeps your Cordial contact database, event history, and audience lists in sync with your warehouse data.

Prerequisites

• A Cordial account with API access enabled
• A Cordial REST API key with write permissions for contacts, events, and lists
• Your Cordial API domain (check your Cordial dashboard URL to determine the correct region)

Authentication

Cordial uses API Key authentication via HTTP Basic Auth.

1. In Cordial, navigate to Administration > API Keys
2. Create a new API key or copy an existing one with write permissions
3. Paste the key into the API Key field in Zeotap

The API key is sent as the username in HTTP Basic Auth with an empty password.

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Contacts

email, first_name, last_name, phone, company, city, state, postal_code, country, channels.email.subscribeStatus, channels.sms.address

Custom Events

email, a (event action), ts (event timestamp), properties

Orders

email, orderID, status, totalAmount, items

How It Works

1. Contacts: Zeotap sends contact data via the Cordial POST /v2/upsertContact/batch endpoint in batches of up to 100 contacts per request. Each contact is identified by email address using the identifiers and identifiersPriority fields in the Cordial payload format.

2. Custom Events: Events are sent via POST /v2/contactactivities/batch in batches of 100. Each event must include the contact email and an action identifier (a field).

3. Orders: Order data is sent via POST /v2/orders/batch in batches of 100. Orders are associated with contacts by email address.

4. Audience Syncs: When a list name is configured, Zeotap manages list membership via POST /v2/addContactsToList (add) and POST /v2/removeContactsFromList (remove). Mirror mode upserts added contacts, adds them to the list, and removes contacts that are no longer in the audience from the list.

Rate Limits

Cordial enforces per-second rate limits by HTTP method and endpoint. If rate limits are exceeded, the API returns HTTP 429 (Too Many Requests). Zeotap automatically retries with exponential backoff when rate limits are hit.

Default rate limits vary by account tier. Contact Cordial support if you need higher limits for large syncs.

Best Practices

• Use email as the primary identifier — Cordial matches contacts by email address. Ensure your email field is consistently formatted and valid.
• Pre-create custom attributes — Contact attributes beyond the standard fields must be created in Cordial before syncing. Navigate to Data > Contact Attributes to set up custom fields.
• Configure list name for audience syncs — If you plan to use audience sync modes (add/remove/mirror), set the List Name in target settings.
• Choose the correct API domain — Check your Cordial dashboard URL: if it contains usw2, use api.usw2.cordial.io; otherwise use api.cordial.io.
• Batch your syncs — Zeotap automatically batches requests (100 per API call), but scheduling syncs during off-peak hours can help avoid rate limit issues.

Troubleshooting

Authentication failed: invalid API key

Verify that your API key is correct and has not been revoked. In Cordial, go to Administration > API Keys to confirm the key is active and has the necessary permissions.

403 Forbidden errors

Your API key may lack the required permissions. Ensure the key has write access to contacts, events, and lists. Contact your Cordial account administrator to update API key permissions.

Contact not updating

Cordial identifies contacts by email address. Verify that:

• The email field is correctly mapped
• The email address is valid and matches an existing contact
• Custom attributes are pre-created in Cordial before syncing

List not found

If audience sync operations fail with a list error, verify that:

• The list name in your target settings matches exactly (case-sensitive)
• The list exists in Cordial under Audience > Lists
• Your API key has permissions to manage list membership

Rate limit exceeded (429)

Zeotap retries automatically on 429 responses. If syncs consistently fail due to rate limits:

• Reduce sync frequency
• Schedule syncs during off-peak hours
• Contact Cordial support to increase your rate limits

Events not appearing

Custom events require both an email field (to associate with a contact) and an a field (event action name). Verify both are mapped correctly. Events for non-existent contacts may be silently dropped.

Orders not syncing

Ensure the email field is mapped to associate orders with contacts. The orderID field should contain unique order identifiers. Verify that your API key has write access to the orders endpoint.