Cordial setup for Data Activation

The Data Activation connector for Cordial enables you to synchronize your contacts from the Data Activation into Cordial contact lists. This integration allows you to build and manage contact segmentation for email marketing campaigns directly from your audience and journey orchestrations.

Here's how this integration delivers value:

• Seamless audience activation: Launch email campaigns in Cordial using audiences and journeys built in the Data Activation, which are then sent to Cordial for targeting and activation.

• Automatic list management: Add contacts to Cordial lists when profiles enter audiences or journeys, and remove them when they leave—keeping your Cordial segments synchronized.

• Cross-channel marketing: Enable personalized email campaigns in Cordial based on your unified customer data from the Data Activation.

• Flexible list creation: Optionally create new contact lists in Cordial automatically when they don't exist, simplifying the setup process.

When added to an audience or journey step, Cordial:

1. Receives contact information from profiles that enter or exit the step (including the contactId and other relevant profile data)

2. Authenticates with Cordial using the API key you provided

3. Executes add or remove syncs with Cordial based on the audience or journey action:

   • When adding contacts, the specified Contact List ID is added to the contact in Cordial

   • When removing contacts, the Contact List ID is removed from the contact in Cordial

This integration ensures your marketing audiences remain synchronized with Cordial contact lists, supporting consistent targeting and personalization.

Destination connector overview

Before you begin

Before configuring the Cordial, make sure that you have the following details set up:

• An active Cordial account

• API access enabled in Cordial

• A Cordial API key with permissions to manage contact lists and contacts

Ensure that your API key is stored securely—you'll need it when configuring the connector in the Data Activation.

Create an API key in Cordial

Before creating the connector in the Data Activation, generate an API key in Cordial:

1. Log in to your Cordial account.

2. Navigate to Settings → API Keys.

3. Click New to add an API key.

4. Provide the following details:

   • API key name: Choose a clear, descriptive name (for example, "Data Activation Integration") to help you identify this key later

   • Permissions: Make sure the key includes at least the ability to retrieve account lists and manage contacts

5. Save the API key.

6. Copy the key and store it securely—you'll need to enter it when creating the Cordial connector.

For detailed instructions, see Cordial's API Key documentation.

Instructions

Step 1: Configure destination

1. On the Data Activation platform, select Connectors in the left-side navigation bar.

2. Select Server to Server and click New Connector.

3. Select Cordial. The form requires the following information:

   • Name: A display name for your connector, used throughout the Data Activation UI

   • Region: The geographic region your Cordial account is hosted in. Available options: usw1, usw2, use1. Select the correct region—an incorrect region will prevent authentication

   • API Key: The API key generated in Cordial (sensitive field)

Note

Cordial accounts use region-specific endpoints. Make sure you select the correct region; otherwise, the connector won't authenticate and can't be created.

Step 2: Add the destination connector to an audience or journey

When adding the Cordial connector to an audience or journey, configure the following:

• Contact list name: The name of the Cordial contact list where contacts will be added or removed. This name must either match an existing list in your Cordial account, or be a new list name that will be created automatically (if the checkbox below is enabled)

• Automatically create Contact List: When checked, if the specified list name does not exist in Cordial, a new list will be created automatically when the contact sync data is received. When unchecked, if the list name does not exist, the sending process may fail with an error

Contact list name requirements:

• Only lowercase letters, digits, or underscores allowed

• Maximum length: 128 characters

How Contact ID data is collected

Before you can send contact IDs to Cordial using the connector, ensure that the Data Activation is receiving and storing these IDs for your customers. The platform supports several methods to collect and store the contactId customer identifier:

1. Data Imports: Upload contact data via batch file import methods. Map your contactId data to user profiles during import so it's available for targeting in audiences and journeys.

2. Open APIs: Use the Data Activation APIs to programmatically map contact data to user profiles.

3. Store Mapping Tag (Website Tag): Use the Store Mapping tag, implemented as a JavaScript snippet, for collecting visitor identifiers from your website.

Connector limitations and known issues

• Batch size limit: Maximum 100 contacts per API request

• No list retrieval: Managing lists in Cordial cannot be done from the Data Activation because there are no available APIs to retrieve or create lists directly. Contact list names must be entered manually

• Contact list name restrictions: Only lowercase letters, digits, or underscores allowed; maximum 128 characters

• Contacts must exist in Cordial: The contactId must already exist in Cordial for contacts to be added to lists successfully

Error handling

Cordial error messages are displayed in the Data Exchange section of the audience or journey. Common errors include:

• Access Denied: Authentication Failure: This error indicates that the Cordial API rejected the authentication attempt. Common causes include:

  • The API key is invalid, expired, or pasted incorrectly

  • The API key does not have the required permissions (must be able to retrieve account lists and manage contacts)

  • The region selected does not match the region associated with the API key

  • Recommended action: Double-check the API key and ensure it has the correct permissions. Also, verify that the correct region is selected during connector setup—an incorrect region can prevent authentication.

For more information, see Cordial API documentation.

FAQ

What identifier is used to match contacts?

The connector uses the Cordial contactId (mapped to partner number 2005) to identify contacts. This ID must be collected and stored in the Data Activation before you can use the connector.

Can I create a new contact list automatically?

Yes. When adding the connector to an audience or journey, check the "Automatically create Contact List" option. If the specified list name doesn't exist in Cordial, a new list will be created when the first contact sync data is received.

Why can't I select from existing Cordial contact lists?

Cordial's API does not provide an endpoint to retrieve existing contact lists. You must enter the contact list name manually, matching the exact name used in your Cordial account.

What happens if I enter an incorrect region?

The connector will fail to authenticate and cannot be created. Make sure to select the region that matches your Cordial account (usw1, usw2, or use1).