# How can we help?

## Search

The Segment integration documented on this page is the legacy (non-actions) version. We recommend using the [latest (actions) version](https://support.cordial.com/hc/en-us/articles/9221698990733).

## Segment contact data types

Here are the types of Segment contact data Cordial ingests using the non-actions (classic) framework:

- **Identify:** Contact identification data unique to each contact.
- **Group:** Contact group associations, which are mapped to Cordial's lists.
- **Track:** Actions and action properties, also known as events, the contact has performed.
- **Page:** Contact's website page view records including page properties.

## Enable Segment as a source

Complete these steps to activate the destination using the Cordial API key as well as enable the integration via API call.

## Activate the destination using Cordial API key

1. Create an API key in your Cordial account using the wildcard IP address of: 0.0.0.0/0. [Learn more about creating API keys in Cordial here](https://support.cordial.com/hc/en-us/articles/115005365087).

2. Log in to your Segment account.

3. Once logged in, paste this URL into your browser: [https://app.segment.com/WORKSPACE/destinations/catalog/cordial](https://app.segment.com/WORKSPACE/destinations/catalog/cordial)

- Replace WORKSPACE with your Segment workspace name.
   - In the example below, WORKSPACE is **acme** (use all lower case).

4. Paste your Cordial API key and select **Activate Destination**.

Certain Cordial attributes designated to store Segment attribute values may need to be created as unique and sparse index fields. Please contact your Client Success Manager for additional assistance.

## Enable the integration using an API call

In order to enable the integration in your Cordial account, you must make the following API call:

#### POST https://admin.cordial.io/api/integrations/segment

| Method | URI Path |
| --- | --- |
| POST | https://admin.cordial.io/api/integrations/segment |
| Enables the Segment integration using the appropriate JSON body. |

#### Parameters

\* Required

| Parameter | Type | Description | Example |
| --- | --- | --- | --- |
| \*name | string | The name of the integration to be enabled. "segment" should be used to enable the Segment integration. | segment |
| \*enabled | boolean | Enables or disables the integration. | true or false |

## Supported Segment functions

Cordial supports the `identify`, `track`, `group`, and `page` methods.

- Data should post to: [http://integrations.cordial.io/segment](http://integrations.cordial.io/segment)

### Identify

Segment data is passed through to Cordial using this endpoint, where 'user' in the URL parameters should be set to the Segment API key. The `userId` in the dataset will be saved to a Cordial attribute designated to store the Segment identifier.

- If the `userId` passed is valid and known, the contact in Cordial will be updated with any mapped values set up in the integration. Based on the example configuration above, `first_name`, `userId`, `address.state`, and `email` will populate or replace the corresponding values in Cordial.
- If the `userId` passed is valid but does not correspond to a Cordial contact, the contact will be created and assigned any mapped values.
- If the `userId` passed is invalid, an error will be returned.

### Group

#### Supported data parameters

| Segment key | Type | Cordial mapping |
| --- | --- | --- |
| `userId` | string | Primary or secondary contact identifier value such as cID, email or a custom identifier. |
| `groupId` | string | list ID |

- If the `userId` passed is valid and known, and the `groupId` passed is valid and known, the contact will be added to the list in Cordial.
- If the `userId` passed is invalid, an error will be returned.

Make sure there is a minimum delay of five seconds between the Identify call and the Group call for new users.

## Cordial lists: add or remove contacts

To make the process of adding and removing contacts from existing [Cordial lists](https://support.cordial.com/hc/en-us/articles/115005528428) more efficient, the list names can be prefixed by `grp_` and passed as traits of an identify call. Lists prefixed by `grp_` accept the following values: 1 and 0 or true and false to indicate if a contact should be added or removed from the list.

The example below demonstrates how to add a new contact to existing Cordial WelcomeSeries and NewUsers lists. To remove a contact from your lists instead, simply use 0 or false values in place of 1 and true.

```
"traits": {
"grp_WelcomeSeries": 1,
"grp_NewUsers": true
}
```

### Track

#### Supported data parameters

| Segment key | Type | Cordial mapping |
| --- | --- | --- |
| `userId` | string | Primary or secondary contact identifier value such as cID, email or custom identifier. |
| `event` | string | Event name. |
| `properties` | object | Event properties (optional). |

- If the `userId` passed is valid and known, the event and its properties will be attributed to the contact in Cordial.
- If the `userId` passed is invalid, an error will be returned.

### Page

#### Supported data parameters

| Segment key | Type | Cordial mapping |
| --- | --- | --- |
| `userId` | string | Primary or secondary contact identifier value such as cID, email or custom identifier. |

- If the `userId` passed is valid and known, a page view event will be attributed to the contact in Cordial.
- If the `userId` passed is invalid, an error will be returned.

## Optional advanced configuration

### PUT https://admin.cordial.io/api/integrations/segment

| Method | URI Path |
| --- | --- |
| PUT | https://admin.cordial.io/api/integrations/segment |
| Updates the Segment integration using the appropriate JSON body.<br>You can remap segment fields using the optional attributeMapping parameter. |

#### Parameters

\* Required

| Parameter | Type | Description | Example |
| --- | --- | --- | --- |
| attributeMapping | Comma separated array of two name/value pairs. | Used to remap Segment fields to Cordial attribute keys. | true or false |
| ignoreFields | Array of comma separated values. | Used to blacklist Segment fields from being passed to Cordial. | ["website"] |

#### Example JSON request (with attributeMapping and ignoreFields)

The following will remap Segment fields to existing Cordial attribute keys and ignore the "website" field.

```
{
    "name":"segment",
    "enabled":true,
    "attributeMapping":[
        {"segmentField":"first_name","cordialKey":"fname"},
        {"segmentField":"user_id","cordialKey":"extid"},
        {"segmentField":"address.state","cordialKey":"state"},
        {"segmentField":"email","cordialKey":"channels.email.address"}
    ],
    "ignoreFields":["website"]
}
```

### GET https://admin.cordial.io/api/integrations

Retrieve a JSON list of integrations you have set up with Cordial.