How can we help?

Send Data from Segment to Cordial

Overview

With our Segment 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.

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

Segment contact data types

Here are 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 Segment as a source

Complete these steps to activate 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 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.

Note: Certain Cordial attributes designated to store segment attribute values may need to be created as unique and sparse index fields. Please contact your Client Sucess 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.

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.

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

Note: 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

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.

Comments

0 comments

Please sign in to leave a comment.