# Cordial (Actions) Destination [Cordial](https://cordial.com/) 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. > \[!NOTE] > > This page is about the [Actions-framework](/docs/segment/connections/destinations/actions/) Cordial Segment destination. There's also a page about the [non-Actions Cordial destination](/docs/segment/connections/destinations/catalog/cordialio/). 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](mailto:support@cordial.com). ## Benefits of Cordial (Actions) vs Cordial Classic 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. ## Getting started To enable destination actions to connect to Cordial: 1. 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](https://support.cordial.com/hc/en-us/articles/115005365087). 2. From the Segment web app, click **Connections > Catalog**. 3. Search for the **Cordial (Actions)** destination item in the left navigation, and click it. 4. Click **Configure Cordial**. 5. Select the Source you want to connect to Cordial (Actions). ## Destination Settings | Field | Description | Required | Type | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | | API Key | Your Cordial API Key | Yes | password | | Endpoint | Cordial API endpoint. Leave default, unless you've been provided with another one. \[See more details]\(https://support.cordial.com/hc/en-us/sections/200553578-REST-API-Introduction-and-Overview) | Yes | string | | User ID attribute key | Cordial string unique attribute key to store Segment User ID in (e.g. \`segment\_id\`) | No | string | ## Available Actions Build your own Mappings. Combine supported [triggers](/docs/segment/connections/destinations/actions/#components-of-a-destination-action) with the following Cordial-supported actions: > \[!NOTE] > > Individual destination instances have support a maximum of 50 mappings. * [Add Contact to List](#add-contact-to-list-1) * [Remove Contact from List](#remove-contact-from-list-1) * [Create Contactactivity](#create-contactactivity) * [Upsert Contact](#upsert-contact-5) * [Upsert Order](#upsert-order) * [Remove Product from Cart](#remove-product-from-cart) * [Add Product to Cart](#add-product-to-cart) * [Merge Contacts](#merge-contacts) ### Add Contact to List 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"` | Field | Description | Required | Type | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | | User Identities | 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. | No | OBJECT | | Group ID | Segment group id. Required. | Yes | STRING | | List name | Cordial list name. Optional. If list name is empty, the name of the list will be set to segment\_\[groupId]. | No | STRING | ### Remove Contact from List Remove Contact from Cordial List Remove Contact from List is a **Cloud** action. | Field | Description | Required | Type | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | | User Identities | 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. | No | OBJECT | | Group ID | Segment group id. Required. | Yes | STRING | ### Create Contactactivity Create a new contact activity. Create Contactactivity is a **Cloud** action. The default Trigger is `type = "track" or type = "page"` | Field | Description | Required | Type | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | | User Identities | 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. | No | OBJECT | | Event name | Event name. Required. | Yes | STRING | | Event timestamp | Event timestamp. Optional. Date format is ISO 8601 standard. If empty, the request upload time will be used. | No | DATETIME | | Event properties | An object of additional event attributes. Optional. | No | OBJECT | | Event context | Event context as it appears in Segment. Optional. We use context to capture event metadata like sender ip and device info. | No | OBJECT | ### Upsert Contact Create or update a contact in Cordial. Upsert Contact is a **Cloud** action. The default Trigger is `type = "identify"` | Field | Description | Required | Type | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | | User Identities | 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. | No | OBJECT | | Contact Attributes | 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\`. | No | OBJECT | ### Upsert Order 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"` | Field | Description | Required | Type | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | | User Identities | 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. | No | OBJECT | | Order ID | Internal identifier of an order | Yes | STRING | | Order purchase date | Order purchase date | Yes | DATETIME | | Order status | Order status (e.g. completed/cancelled/returned) | Yes | STRING | | Order total | Order total amount | Yes | NUMBER | | Discount application | Discount application data, allowed fields: type (only 'fixed' as of now), amount (float discount amount, e.g. 10.45) | No | OBJECT | | Order properties | Additional order properties (e.g. affiliation/tax/revenue) | No | OBJECT | | Order items | Order items | Yes | OBJECT | ### Remove Product from Cart Removes product from Cordial contact cart Remove Product from Cart is a **Cloud** action. The default Trigger is `type = "track" and event = "Product Removed"` | Field | Description | Required | Type | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User Identities | 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. | No | OBJECT | | Product ID | Internal identifier of a product | Yes | STRING | | Quantity | Quantity of a product | Yes | INTEGER | ### Add Product to Cart Add product to Cordial contact cart Add Product to Cart is a **Cloud** action. The default Trigger is `type = "track" and event = "Product Added"` | Field | Description | Required | Type | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User Identities | 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. | No | OBJECT | | Product ID | Internal identifier of a product | Yes | STRING | | SKU | SKU of a product | Yes | STRING | | Quantity | Quantity of a product | Yes | INTEGER | | Category | Category of a product | Yes | STRING | | Name | Name of a product | Yes | STRING | | Description | Description of a product | No | STRING | | Price | Price of a product | No | NUMBER | | URL | URL of a product | No | STRING | | Image URL | Image of a product | No | STRING | | Properties | Properties of a product (e.g brand, color, size) | No | OBJECT | ### Merge Contacts Merge contacts in Cordial. Merge Contacts is a **Cloud** action. The default Trigger is `type = "alias"` | Field | Description | Required | Type | | ------------------------ | ------------------------------------------- | -------- | ------ | | New Segment User ID | New Segment User ID value | No | STRING | | New Segment Anonymous ID | New Segment Anonymous ID value | No | STRING | | Previous Segment ID | Previous Segment User or Anonymous ID value | Yes | STRING | ## Migration from the classic Cordial destination ### User Identities Mappings 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. ### Updating contacts 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. ### Sending events 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. ### Adding users to and removing from lists 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.