Sending Data from Segment to Cordial

Overview

The Segment integration enables Cordial as a Segment Destination, allowing you to send contact data from your Segment account to Cordial. Segment contact data is seamlessly integrated into the appropriate data collections within Cordial. You can then use Cordial's powerful data and messaging tools to build audiences, personalize message content, and trigger messages across multiple channels.

The types of Segment contact data Cordial currently ingests:

• 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 the Segment Integration

You can enable the Segment integration by following the steps outlined below. Please complete the steps for activating the destination using the Cordial API key as well as enabling 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.
2. Log into 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 activate the destination.
   

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.

Note: Make sure that there is a minimum delay of 5 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.

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