Segment: as a data destination

Set up as a Segment Destination and pipe data from any one of Segment’s hundreds of Source integrations into your workspace.

You can find complete detail on the Destination page in Segment’s documentation.

Set up a Segment Destination integration

 Try out Segment Destination Actions

The newer Segment Destination Actions integration supports anonymous events and lets you filter the events that you send to, helping you control the data that you send to
  1. Go to Settings > Integrations and click the Segment Destination integration.
  2. Click Configure Segment.
  3. Pick the Workspace and Source you want to associate your integration with, and then click Allow.

You can also set up this integration from the Segment interface using the API credentials provided on the Segment Destination page.

Identifying people through segment

If you’re not familiar with the Segment API, take a look at the Identify method. It’s very similar to Adding or Updating people in

Here’s an example request:

analytics.identify('userId123', {
  email: ''

When you identify a new user, the user is added to your workspace. If the user already exists, the request updates the existing person’s attributes.

If your workspace supports both email and id as identifiers (the default setting as of June 2021), you can identify people either by id or their email trait.

This provides a path to identify people who enter your system as leads (by email) and then assign them an ID in when they become a customer or user.

  • If you don’t have an ID, pass a person’s email address as the userId in the identify call. maps this value to a person’s email attribute.
  • If you have an ID, set the userId in the identify call to the person’s ID and pass email as a trait. This sets both a person’s id and email attributes in If you previously identified a person by email, your request updates that person and assigns them an id.

Converting leads to customers

If your workspace supports both id and email identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace., you may want to identify a lead first by email, and then assign them an id when they become a customer or user.

The lead to customer journey
The lead to customer journey

To create a lead and then assign them an id when they become a customer or user:

  1. Identify a lead by passing their email as the userId. This creates your lead in

        analytics.identify('', {
          // The email address does not belong to anybody
          // so we create a new person
          first_name: 'person',
          interested_in: 'baseball'

  2. Later, when that person becomes a customer, pass their new id as the userId in your Identify call, and pass their email as a trait. We’ll update the lead (who you first identified by email) with the new ID—as long as this person does not already have an id value and the id you use does not already exist.

    analytics.identify('userId123', {
      // the email belongs to the lead you identified in the previous step
      // so we'll assign an id to this person—userId123.
      email: '',
      account_created: 1629224941

In this second request, if the ID already belongs to a person, we’ll attempt to update that person. If the ID and email already exist, you’ll receive an error.

Update email and ID values that have already been set

After you set a person’s email or id value in you cannot change them like normal traits. Instead, if you want to change a non-null identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace., you have to pass a person’s cio_idAn identifier for a person that is automatically generated by and cannot be changed. This identifier provides a complete, unbroken record of a person across changes to their other identifiers (id, email, etc)., in the format cio_<cio_id value> as the userId in your identify call.

analytics.identify('cio_<cio_id value>', {
  email: '',
  id: 'new-id-value'

You can find a person’s CIO ID value by going to a person’s page in interface or by looking up a person with the customers API.

Unsubscribing Users

To unsubscribe a user, simply pass unsubscribed: true in your Segment identify call. Be sure the id and/or email values match the values in You can find these values by selecting a person on the People page, and clicking Attributes. Here is an example that unsubscribes a user:

analytics.identify('userId123', {
    email: '',
    unsubscribed: true

Identifying people in workspaces that only support ID

In older workspaces, or workspaces using “classic” settings, you can only identify people by ID.

You do not need to pass an email address unless you intend to send emails. If you intend to send emails, you must provide the email address as a trait labeled email.

Segment Suppression and Deletion

To help comply with GDPR and CCPA regulations, Segment supports a set of Suppression and Deletion tools. These tools are separate from’s own suppression and deletion tools.

In Segment, suppressed users are blocked across all sources; any message sent to Segment via a suppressed userId is blocked at their API (with the exception of device-mode destinations). Suppressions are not synchronized between Segment and, however when you suppress and delete a customer via Segment’s UI, that deletion is passed along to to ensure that the suppressed and deleted person is removed.

Segment Alias Call does not support alias calls or anonymous events from Segment. Segment uses ananonymousId trait to identify users, and it’s not possible to connect anonymous user data with a newly created person in As a result, you could end up with duplicate profiles. You might have come across this issue if You’re integrated via Segment and want to change ids.

Rather than using anonymous events, we suggest that you identify people by email, and then assign them an id as they become customers. See identifying users through segment above.

If you send an identify call with some attributes attached, we look at the identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. in the call. If we don’t recognize any of the identifiers in the call, we create a new user with those attributes. If any of the identifiers in the call already exist, we update only the attributes that are different compared to the previous call. We do not update or change the id. So if the id is new to, we create a new (duplicate) user.

Resolve existing duplicates

If you have duplicate people in your system, you can resolve profiles through the following process:

  1. Export a CSV of your customers from the People page by clicking on the Export to CSV button.
  2. Identify the duplicates. We recommend keeping the first instance of each—the one with an oldest created_at timestamp.
  3. Create a new CSV file with all of the people (by id or email) you want to delete.
  4. Delete those users with our API.

Prevent new users from causing duplicates

For new users, we strongly suggest you identify people by email if they do not yet have an ID.

  1. Pass email as the userId in Segment’s identify call.
  2. Update a person’s ID using an identify call after they sign up for your service.

Anonymous Events from Segment

If you want to send anonymous events from Segment, you should consider upgrading to Segment’s new Destination Actions feature. We have instructions to set up Destination Actions with here.

If you can’t upgrade to Segment’s Destination Actions feature, and you need to message a customer before they’ve signed up, you should record an event by email and then send an invite campaign to people in who have an email address but do not have an ID.

As always, if you need any help with this process or have any questions, please let us know!

Copied to clipboard!