The Segment integration documented on this page is the legacy (non-actions) version. We recommend using the latest (actions) version.

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.

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

• 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

Parameters

* Required

Supported Segment functions

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

• Data should post to: 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

• 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 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 contract 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.

List names prefixed by grp_ must match the names of your lists in Cordial. If the list names do not match, or the lists do not already exist in Cordial, the request will not be successful.

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

Track

Supported data parameters

• 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

• 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

Parameters

* Required

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.