Cordial Connector Setup Guide

API Information

This connector uses the following vendor API:

• API Name: Cordial API
• API Version: v1.0
• Documentation: Cordial API

Configuration

Navigate to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.

After adding the connector, configure the following settings:

• API Key
  Cordial uses HTTP Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account. This key is then used as the username for your BA credentials. For more information, see RESTful API Summary and Usage.

  You must add the Tealium IP addresses to your API_KEY whitelist in Cordial.

• Path-URL
  Select one of the following Path URLs or type it manually.

  • https://api.cordial.io/v2/ - Use this URL if your admin panel URL is https://admin.cordial.io/.
  • https://api.usw2.cordial.io/v2/ - Use this URL if your admin panel URL is https://usw2.admin.cordial.io/.

Click Done when you are finished configuring the connector.

Actions

Action Name	AudienceStream	EventStream
Upsert contact	✓	✓
Add cart to contact	✗	✓
Record contact activity (event)	✓	✓
Add or delete a contact from an account list	✓	✓
Create a new order	✗	✓
Send notification	✓	✓
Record contact activity (batch)	✓	✓

Click Continue to configure the connector actions. Enter a name for the action and then select the action type from the drop-down menu.

The following section describes how to set up parameters and options for each action.

Upsert contact

Parameters

Parameter	Description
Contact Identifier Key	The contact identifier key. For example, email, cID.
Contact Identifier Value	The contact identifier value.
Email Address	Unique channel address to identify and reference the contact.
Subscribe Status	Promotional messages will not be sent unless set to subscribed. Default is none. Possible values: none, subscribed or unsubscribed.
Suppress Triggers	If true, suppresses message triggers that are based on updates to contact attribute values. Default is true.
Force Subscribe	If unsubscribed, this key must be used to update subscribe status to subscribed. Possible values: true, false.
Invalid	No email message will be sent unless set to false. Default is false. Possible values: true, false.

Optional Parameters

Parameter	Description
Account Lists	Adds or removes the contact from a list. Possible values: true, false.
String Parameters	Adds a string attribute value when the attribute type is set as string.
Number Parameters	Adds a number attribute value when the attribute type is set as number.
Date Parameters	Adds a date attribute value when the attribute type is set as date.
Geo Parameters	Adds a geo attribute value when the attribute type is set as geo. Note that geo attributes contain following set schema of key names: Street Address Street Address 2 City State Postal Code Country ISO Time Zone Location Latitude Longitude
Array Parameters	Adds array attribute values when the attribute type is set as array. The default behavior is to replace the array value with the provided one. An object specifying add/remove behavior can be specified to override the default. If the max items limit is exceeded (default is 25), newer values will replace the oldest values.

Add cart to contact

Parameters

Parameter	Description
Contact Identifier Key	The contact identifier key. For example, email, cID.
Contact Identifier Value	The contact identifier value.
Message Contact ID	The message contact ID.
Customer ID	The customer ID.
Link ID	The link ID.
Cart URL	The cart URL.

Cart Item Parameters

Parameter	Description
Product ID	The item identifier.
Name	The item name.
SKU	The item number.
Category	The item category.
Quantity	The quantity in the cart.
Images	The image names or paths. If item has more than one image the provided value will be split by comma (,).
Item Price	The price per item.
Description	The item description.
URL	The link to the item.

Record contact activity (event)

Parameters

Parameter	Description
Contact Identifier Key	The contact identifier key. For example, email, cID.
Contact Identifier Value	The contact identifier value.
Action	Defines a custom action to create, such as browse, order, cart, or any other custom action. The maximum length of the parameter is 40 characters. Note that reserved actions cannot be added via the POST method. For more information, see Contact activities (events) API
Action Timestamp	Action timestamp. If undefined, the current date and time will be used. Date format is ISO 8601 standard.
Properties	An object of additional event attributes. The default maximum number of properties an event can have is 1,000. Note that property keys consisting of numeric-only values (such as 57) or keys containing a dot (such as shoes.color) are stripped.

Add or delete a contact from an account list

Parameters

Parameter	Description
Account List	Select account list or enter a list ID.
Action	Choose action Add or Delete.
Contact Identifier Key	The contact identifier key. For example, email, cID.
Contact Identifier Value	The contact identifier value.

Create a new order

Parameters

Parameter	Description
Contact Identifier Key	The contact identifier key. For example, email, cID.
Contact Identifier Value	The contact identifier value.
Order ID	Unique identifier assigned for the order.
Purchase Date	A date value signifying the purchase data and time. Date format is ISO 8601.
mcID	Cordial ID that represents the account, contact and the message. Required to track revenue attribution to an email.
msID	Cordial ID that represents the message.
Customer ID	An ID value assigned by the eCommerce or CRM system.
Link ID	Cordial ID that represents the message and link. Required to track revenue attribution to a specific link.
Total Amount	Auto-calculated as the sum of each item.amount.
Tax	The amount of the tax.
Shipping and Handling	The amount charged for shipping and handling.
Properties	key-value pairs describing the properties of the order.

Shipping Address

Parameter	Description
Address	The address.
City	The city.
Country	The country.
Name	The name.
Postal Code	The postal code.
State	The state.

Billing Address

Parameter	Description
Address	The address.
City	The city.
Country	The country.
Name	The name.
Postal Code	The postal code.
State	The state.

Item Parameters

Parameter	Description
Product ID	The item identifier.
Name	The item name.
SKU	The item number.
Category	The item category.
Quantity	The number of items purchased. Defaults to 1 if not passed.
Images	The image names or paths. If item has more than one image the provided value will be split by comma (,).
Item Price	The price per item.
Description	The item description.
URL	The link to the item.
Amount	Auto-calculated as qty x itemPrice. If a value not equal to qty x itemPrice is passed, it is overwritten.
Tags	A comma separated array of values to describe the product. Only accepts alphanumeric characters or dashes.

Send notification

Parameters

Parameter	Description
Automation Template	Select template or provide template ID.
Email	The email.
CID	The contact ID.
Identify By	Specifies which identifier key in the request body should be used to look up the contact.
External Variables	The external variables. Supports templates.
Template Variables	Provide template variables as external variables input. For more information, see Connector template variables. Name nested template variables with the dot notation (For example, items.name). Nested template variables are typically built from data layer list attributes.
Templates	Provide templates to be referenced in parameters. For more information, see About connector templates. Templates are injected by name with double curly braces into supported fields. For example, {{SomeTemplateName}}.

Record contact activity (batch)

Batch Limits

This action uses batched requests to support high-volume data transfers to the vendor. Requests are queued until one of the following thresholds is met:

• Max number of requests: 99
• Max time since oldest request: 10 minutes
• Max size of requests: 10 MB

Parameters

Parameter	Description
Host	Specify your Cordial region: usw1: https://integrations-ingest-svc.cordial.com usw2: https://integrations-ingest-svc.usw2.cordial.com use1: https://integrations-ingest-svc.use1.cordial.com
Source	Data source. The default value is TEALIUM.

Identifiers

Parameter	Description
Contact ID	Contact ID.
Email	Contact email address.
Phone	Contact phone number.
Custom ID	Primary or secondary keys set up in your account. For more information, see Cordial: Primary v. secondary keys.
Identifiers Priority	The order in which identifiers are used when searching for a contact.

Contact Activity

Parameter	Description
Name	Event name.
Time	Action timestamp. If undefined, the current date and time is used. Date format is ISO 8601 standard.
City	Name of the city.
Country	Name of the country.
Latitude	Latitude coordinate.
Longitude	Longitude coordinate.
Device	Specific device model.
Platform	Operating system of the device.
Browser	Browser used on the device.
IP	IP address of the device.
Robot	Indicates whether the device is operated by a bot.
Device Type	Type of device, such as mobile or desktop.
Contact Activity Properties	Additional event attributes. By default, each event can have up to 1,000 properties. Property keys that are numeric-only (for example, 57) or contain a dot (for example, shoes.color) are stripped.
Contact Attributes	The attributes to set if a contact doesn’t exist and should be created.

Contact Options

Parameter	Description
Force subscribe	Force subscribe.
Merge allowed	Merge allowed.
Mergeable secondary keys	Secondary keys, such as email, that can be used to merge contact records.
Can be created	(Optional) The default value is false. Creates a new contact if it doesn’t already exist.
Can be updated	(Optional) The default value is false. Updates the contact if it already exists.
Batch Time To Live	Time to live should be between 1 and 60 minutes. The default value is 10 minutes.