Cordial (Actions) Destination
Cordial is an all-in-one marketing platform that enables brands to collect, normalize, and activate real-time data from anywhere in your technology stack to create and deliver tailored messages that flex and adapt to changing customer signals.
Good to know
This page is about the Actions-framework Cordial Segment destination. There's also a page about the non-Actions Cordial destination. Both of these destinations receive data from Segment.
This destination is maintained by Cordial. For any issues with the destination, contact the Cordial Support team.
Cordial (Actions) provides the following benefits over the classic Cordial destination:
- Transparent data mapping. The Classic Cordial destination receives data from Segment as is. The Cordial backend then converts those Segment events to Cordial's format and clients have limited control over this conversion. The Cordial (Actions) destination allows clients to fully define their own mappings of Segment events, making sure they receive data structured specifically for their needs.
- Only sends the data you need. With Cordial (Actions) you can define only those destination actions and mappings that make sense for your use cases, while Cordial Classic always sends four predefined API calls: identify, track, group, and page.
- Sends Engage components to Cordial. With Cordial (Actions) it's possible to define action mappings that will send audiences and user computed traits defined in the Segment Engage platform to Cordial.
To enable destination actions to connect to Cordial:
- Make sure you have your Cordial API Key. To create a new API key, navigate to the account settings menu and select API Keys. Learn more.
- From the Segment web app, click Connections > Catalog.
- Search for the Cordial (Actions) destination item in the left navigation, and click it.
- Click Configure Cordial.
- Select the Source you want to connect to Cordial (Actions).
Your Cordial API Key
Cordial API endpoint. Leave default, unless you've been provided with another one. See more details
Optional
Cordial string unique attribute key to store Segment User ID in (e.g. segment_id)
Build your own Mappings. Combine supported triggers with the following Cordial-supported actions:
Mapping limits per destination
Add contact to a list. If the list does not exist in Cordial it will be created.
Add Contact to List is a Cloud action. The default Trigger is type = "group"
Optional
An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.
Segment group id. Required.
Optional
Cordial list name. Optional. If list name is empty, the name of the list will be set to segment_[groupId].
Remove Contact from Cordial List
Remove Contact from List is a Cloud action.
Optional
An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.
Segment group id. Required.
Create a new contact activity.
Create Contactactivity is a Cloud action. The default Trigger is type = "track" or type = "page"
Optional
An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.
Event name. Required.
Optional
Event timestamp. Optional. Date format is ISO 8601 standard. If empty, the request upload time will be used.
Optional
An object of additional event attributes. Optional.
Optional
Event context as it appears in Segment. Optional. We use context to capture event metadata like sender ip and device info.
Create or update a contact in Cordial.
Upsert Contact is a Cloud action. The default Trigger is type = "identify"
Optional
An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.
Optional
Contact attributes to update. Optional. Contact attributes must exist in Cordial prior to updating. Attributes that do not exist in Cordial will be ignored. Complex attribute types to be mapped via dot notation, for example, cordialPerson.first_name -> traits.segmentPerson.firstName, cordialPerson.last_name -> traits.segmentPerson.lastName. Segment trait address can be mapped directly to geo Cordial attribute: geo_cordial_attribute -> traits.address.
Upserts order to Cordial
Upsert Order is a Cloud action. The default Trigger is event = "Order Completed" or event = "Order Updated" or event = "Order Refunded" or event = "Order Cancelled"
Optional
An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.
Internal identifier of an order
Order purchase date
Order status (e.g. completed/cancelled/returned)
Order total amount
Optional
Discount application data, allowed fields: type (only 'fixed' as of now), amount (float discount amount, e.g. 10.45)
Optional
Additional order properties (e.g. affiliation/tax/revenue)
Order items
Removes product from Cordial contact cart
Remove Product from Cart is a Cloud action. The default Trigger is type = "track" and event = "Product Removed"
Optional
An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.
Internal identifier of a product
Quantity of a product
Add product to Cordial contact cart
Add Product to Cart is a Cloud action. The default Trigger is type = "track" and event = "Product Added"
Optional
An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.
Internal identifier of a product
SKU of a product
Quantity of a product
Category of a product
Name of a product
Optional
Description of a product
Optional
Price of a product
Optional
URL of a product
Optional
Image of a product
Optional
Properties of a product (e.g brand, color, size)
Merge contacts in Cordial.
Merge Contacts is a Cloud action. The default Trigger is type = "alias"
Optional
New Segment User ID value
Optional
New Segment Anonymous ID value
Previous Segment User or Anonymous ID value
Every Cordial destination action needs to be invoked with data identifying a Cordial contact. To identify a contact every destination action has a User Identities field, which maps Segment event fields to Cordial contact identifiers. Each entry in the list represents a contact identifier and how it maps from a Segment event. For example, channels.email.address <- userId or customerId <- traits.customerId. At least one identifier should be valid, otherwise the contact won't be identified and the request will be ignored.
Typically, the User Identities field maps the Segment events userId field to the Cordial secondary identifier field. For example, if Segment's userId field is known to be an email, the mapping will be channels.email.address <- userId, meaning the value of userId will be sent as channels.email.address to Cordial.
If you plan to create and update contacts in Cordial, define the upsertContact destination action. In addition to the User Identities field, the action defines the Contact Attributes field. This field defines an exclusive set of attributes that will be updated in a contact. Typically, you map them from Segment traits. For example, customerId <- traits.customerId. For the Cordial Classic destination, these mappings are stored in Cordial's database. In the Cordial (Actions) destination, they become explicit in the upsertContact destination action mappings.
To send events, define the createContactactivity destination action. In addition to the User Identities field, additional fields such as Event name, Event timestamp, and Event properties may be defined. Refer to documentation for each field when defining the destination action.
If you plan to segment users in Cordial, make sure you define the addContactToList and removeContactFromList destination actions. Both actions require the Segment group ID. addContactToList optionally accepts a list name.
Although optional, you should consider the list name as a required option, because it simplifies segmenting contacts in Cordial based on lists. Lists without a name are called following the segment_[groupId] pattern.