# How can we help?

## Overview

With our [Segment](https://segment.com/) integration, you can send contact data from your Segment account to Cordial, which is seamlessly integrated into the appropriate data collections. From there you can use Cordial's powerful data and messaging tools to build audiences, personalize message content, and trigger messages across multiple channels.

- You can also [send data from Cordial to Segment](https://support.cordial.com/hc/en-us/articles/360010755251).

Certain features in your Cordial account must be preconfigured before the Segment integration can be enabled. Please contact your Client Success Manager for assistance before attempting to enable the integration.

## Latest v. legacy version

The latest version of our integration with Segment uses the actions framework. Benefits of using the latest version include:

- **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 data you need:** With the latest framework, you can define only those destination actions and mappings that make sense for your use cases, while the previous iteration 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.

You can [find documentation for the legacy (non-actions) version of our Segment integration here](https://support.cordial.com/hc/en-us/articles/14600614942605).

## Enable latest integration version (actions framework)

Follow these steps to enable destination actions.

1. Make sure you have your Cordial API Key. To create a new API key, navigate to **Account Settings > API Keys**.

- [Learn more about creating API keys here.](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

| Setting | Description |
| --- | --- |
| API key | Required. Your Cordial API key. |
| Endpoint | Required. Cordial API endpoint. Change the default to <br>- [us-west-1 - https://integrations-ingest-svc.cordial.com](https://integrations-ingest-svc.cordial.com/)<br>- [us-west-2 - https://integrations-ingest-svc.usw2.cordial.com](https://integrations-ingest-svc.usw2.cordial.com/)<br>- [us-east-1 - https://integrations-ingest-svc.use1.cordial.com](https://integrations-ingest-svc.use1.cordial.com/)<br>- You can [find more details in our API documentation.](https://support.cordial.com/hc/en-us/sections/200553578-REST-API-Introduction-and-Overview) |
| User ID attribute key | Required. Cordial string unique attribute key to store Segment User ID in (e.g. `segment_id`). **Note:** This attribute should be the secondary key. Contact your CSM for assistance. |

## Scriptable API

Our scriptable API offers asynchronous methods for sending data from Segment to Cordial. This allows you to stream data, send multiple API requests at the same time, and have more precise control over how Cordial interacts with Segment.

You can [use Swagger to access and test our scriptable API offerings](https://integrations-ingest-svc.cordial.com/docs#/). In order to do so, you'll need an API key.

## Supported actions

Combine supported [Segment triggers](https://segment.com/docs/connections/destinations/actions/#components-of-a-destination-action) with the following Cordial-supported actions.

**Mapping limits per destination:** individual destination instances support a maximum of 50 mappings.

- [POST/segment/createContactActivity](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#h_01H2E12G2A54HD756CQYVC29AY)
- [POST/segment/upsertContact](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#h_01H2E12VXE0ZFCSNDK1HHYAQSB)
- [POST/segment/mergeContacts](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#h_01H2BRY8NCKBFSB63V2J8QSZGE)
- [POST/segment/addContactToList](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#h_01H2BRYYWTWKS3D5WDHQ3FV8JW)
- [POST/segment/removeContactFromList](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#h_01H2BRZ8XPH47R2GZBVYZEXQSK)
- [POST/segment/addProductToCart](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#h_01H2E14VNJSZGZP6ZQS01KGZF5)
- [POST/segment/removeProductFromCart](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#h_01H2E1577VWZBYH0VVDK7481PF)
- [POST/segment/upsertOrder](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#upsert-order)

### POST/segment/createContactactivity

Create a new contact activity. Default trigger is:`type = "track" or type = "page"`

- [Parameters](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-1-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-1-1)

| **Parameters** | **Type** | **Description** | **Example** |
| --- | --- | --- | --- |
| segmentIdKey | string | Segment ID key. | See example request. |
| segmentID | string | Segment user ID value. | See example request. |
| anonymousId | string | Segment anonymous ID value. | See example request. |
| userIdentities | object | An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. | See example request. |
| \*action | string | Internal identifier of an action. | See example request. |
| \*time | string/date-time | Action timestamp. Optional. Date format is ISO 8601 standard. If empty, the request upload time will be used. | See example request. |
| properties | object | An object of additional action attributes. Optional. | See example request. |
| context | object | Action context as it appears in Segment. Optional. We use context to capture event metadata like sender IP and device info. | See example request. |
| type | string | Type of action/event. | See example request. |

```json
{
  "segmentIdKey": "segment_id",
  "segmentId": "test-user-ouxty4jxdm",
  "anonymousId": "5cwt1zukfza",
  "userIdentities": {
    "cid": "test",
    "email": "email"
  },
  "action": "click",
  "time": "2020/24/24",
  "properties": {
    "test1": 1,
    "test2": 2
  }
}
```

### POST/segment/upsertContact

Create or update a contact in Cordial. Default trigger:`type = "identify"`

- [Parameters](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-2-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-2-1)

| **Parameters** | **Type** | **Description** | **Example** |
| --- | --- | --- | --- |
| segmentIdKey | string | Segment ID key. | See example request. |
| segmentID | string | Segment user ID value. | See example request. |
| anonymousId | string | Segment anonymous ID value. | See example request. |
| userIdentities | object | 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. | See example request. |
| attributes | object | 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. | See example request. |

```json
{
  "segmentIdKey": "segment_id",
  "segmentId": "test-user-ouxty4jxdm",
  "anonymousId": "5cwt1zukfza",
  "userIdentities": {
    "cid": "test",
    "email": "email"
  },
  "attributes": {
    "test1": 1,
    "test2": 2
  }
}
```

### POST/segment/mergeContacts

Merge contacts in Cordial. Default trigger:`type = "alias"`

- [Parameters](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-3-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-3-1)

| **Parameters** | **Type** | **Description** | **Example** |
| --- | --- | --- | --- |
| segmentIdKey | string | Segment ID key. | See example request. |
| segmentID | string | Segment user ID value. | See example request. |
| anonymousId | string | Segment anonymous ID value. | See example request. |
| \*previousId | string | Previous Segment ID. | See example request. |

```
{
  "segmentIdKey": "segment_id",
  "segmentId": "test-user-ouxty4jxdm",
  "anonymousId": "5cwt1zukfza",
  "previousId": "previous-id"
}
```

### POST/segment/addContactToList

Add contact to a list. If the list does not exist in Cordial it will be created. Default trigger:`type = "group"`

- [Parameters](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-4-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-4-1)

| **Parameters** | **Type** | **Description** | **Example** |
| --- | --- | --- | --- |
| segmentIdKey | string | Segment ID key. | See example request. |
| segmentID | string | Segment user ID value. | See example request. |
| anonymousId | string | Segment anonymous ID value. | See example request. |
| userIdentities | object | An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. | See example request. |
| \*groupID | string | Internal identifier for group. | See example request. |
| listName | string | List name in Cordial. | See example request. |

```json
{
  "segmentIdKey": "segment_id",
  "segmentId": "test-user-ouxty4jxdm",
  "anonymousId": "5cwt1zukfza",
  "userIdentities": {
    "cid": "test",
    "email": "email"
  },
  "groupId": "123",
  "listName": "segmentList"
}
```

### POST/segment/removeContactFromList

Remove contact from Cordial list.

- [Parameters](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-5-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-5-1)

```json
{
  "segmentIdKey": "segment_id",
  "segmentId": "test-user-ouxty4jxdm",
  "anonymousId": "5cwt1zukfza",
  "userIdentities": {
    "cid": "test",
    "email": "email"
  },
  "groupId": "123"
}
```

### POST/segment/addProductToCart

Adds product to cart. Default trigger:`type = "track" and event = "Product Added"`

- [Parameters](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-6-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-6-1)

```json
{
  "segmentIdKey": "segment_id",
  "segmentId": "test-user-ouxty4jxdm",
  "anonymousId": "5cwt1zukfza",
  "userIdentities": {
    "cid": "test",
    "email": "email"
  },
  "productID": "123",
  "sku": "TEST-SKU",
  "qty": 2,
  "category": "Test category",
  "name": "Test product",
  "description": "Test description",
  "itemPrice": 65.32,
  "url": "https://example.com/product",
  "imageUrl": "https://cdn.example.com/product.jpg",
  "properties": {
    "variant": "black",
    "size": "xs"
  }
}
```

### POST/segment/removeProductFromCart

Removes product from Cordial contact cart. Default trigger:`type = "track" and event = "Product Removed"`

- [Parameters](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-7-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-7-1)

| **Parameters** | **Type** | **Description** | **Example** |
| --- | --- | --- | --- |
| segmentIdKey | string | Segment ID key. | See example request. |
| segmentID | string | Segment user ID value. | See example request. |
| anonymousId | string | Segment anonymous ID value. | See example request. |
| userIdentities | object | An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. | See example request. |
| \*productID | string | Internal identifier for a product. | See example request. |
| \*qty | string | Quantity of a product. | See example request. |

```json
{
  "segmentIdKey": "segment_id",
  "segmentId": "test-user-ouxty4jxdm",
  "anonymousId": "5cwt1zukfza",
  "userIdentities": {
    "cid": "test",
    "email": "email"
  },
  "productID": "123",
  "qty": 2
}
```

### POST/segment/upsertOrder

Upserts order to Cordial. Default trigger:`event = "Order Completed" or event = "Order Updated" or event = "Order Refunded" or event = "Order Cancelled"`

- [Parameters](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-8-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/9221698990733-Send-data-from-Segment-to-Cordial-actions#zp-8-1)

```
{
  "segmentIdKey": "segment_id",
  "segmentId": "test-user-ouxty4jxdm",
  "anonymousId": "5cwt1zukfza",
  "userIdentities": {
    "cid": "test",
    "email": "email"
  },
  "orderID": "123",
  "purchaseDate": "2015-12-12T19:11:01.249Z",
  "status": "Completed",
  "properties": {
    "tax": 32.43,
    "affiliate": "Google"
  },
  "items": [
    {
      "productID": "123",
      "sku": "test-sku",
      "name": "test-name",
      "category": "test-category",
      "manufacturerName": "test-brand",
      "itemPrice": 443.23,
      "qty": 2,
      "url": "https://example.com/product",
      "imageUrl": "https://cdn.example.com/product.jpg",
      "properties": {
        "variant": "black",
        "size": "size"
      }
    }
  ]
}
```

## Migration from the legacy 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.

### Update 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.

### Send 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.

### Add and remove users 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.