Legacy Segment integration: non-actions framework – Cordial Knowledge Base

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.

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

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.
Log in to your Segment account.
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).

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

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