Segment destination actions

Use Segment’s destination actions to capture events and shape data from any one of Segment’s Source integrations in, including anonymous events.

 Do you have a standard Segment destination?

This page helps you use with Segment’s new “destination actions” feature. If you’re using as a standard destination, and you don’t want to upgrade, see our standard Segment Destination page.

Unlike our standard Segment Destination integration, the Destination Actions integration supports anonymous events. Segment’s Destination Actions feature lets you filter the events that you send to, helping you determine exactly what data you want to send to your destination. It also lets you map properties from the source event to destination calls, helping you shape information from your source to without having to write code.

Segment’s destination actions feature is in an open beta. Some functionality might be subject to change. If you already have a standard Segment Destination integration and want to upgrade, check out our upgrade path.

Set up Segment Destination Actions

If you want to take advantage of anonymous events from Segment in, you need to use Segment’s Destination Actions feature. This framework makes it easy to map anonymous events that you capture from another source to

  1. In your Segment workspace, go to Destinations and click Add Destination.
  2. Click Destination Actions in the left navigation, and then select Actions.
  3. Click Configure Actions. If prompted, select the source that you want to connect to
  4. Enter your Site ID and API Key.

    You can find your Site ID and API Key credentials under Data & Integrations > Integrations > API.

  5. Click Configure Actions.
  6. Select the Source that you want to connect to your destination and then click Authenticate.
  7. Enter your Site ID and API Key. You can find your Site ID and API Key credentials under Data & Integrations > API.
  8. Select how you want to set up your actions and click Create Destination. In general, you should use Quick Setup and take advantage of our default mappings, but you can also click Customized Setup to filter the events that you send into and re-map event properties. See the section below for more information about filtering and mapping actions.
    Finish setting up a destination action
    Finish setting up a destination action

Filter and Map Actions

When you configure with Destination Actions, the actions are pre-populated with default settings. You can select an action to filter the source events that you send to and map the properties from the source event to the action. If this is something you want to do, you should understand the information that you send in identify and track calls to Segment before you begin.

To get to your Actions, go to Destinations, select your destination, and then click Actions. Select any of the actions to filter the source event and map to the destination event.

  • Use Set up event trigger to filter the event(s) that Segment sends to
  • Use Configure action fields to re-map source properties to
    Set up a destination action for
    Set up a destination action for

For example, if you know that a specific event type represents your leads—people you identify by email address—you may want to filter the event trigger by that event name, and then set the Person ID action field to email. This ensures that the source event represents a person that you identify by email address.

Event tester and common errors

On your destination actions page in Segment, you can go to the Event Tester tab to send test events to validate your action subscriptions. Test events will appear in your event destination as real data; most event types contain a userId, so take care not to inadvertently represent a real person with your test data. You may want to change the userID to the value of a designated “test person” in your workspace.

Use the Type option to determine the type of event you want to test. By default, the Event Tester shows the JSON tab, but you can use the Event Builder for a no-code option to build your event. In either case, the event is pre-formatted, but you can populate properties to better represent your audience.

Common errors include:

The root value is missing the required field url.

The default Page event subscription expects page views as sent from Segment’s JavaScript snippet, which populates URLs at properties.url. You must provide this value in your test event unless you set up a subscription to capture events page views using Segment’s API.

If you capture page view events using Segment’s API, which expects URLs in the name field, you can set up a new subscription on the Actions tab. Set the event trigger when the Event Type is Page and set Page URL to name.

Segment did not send any requests to the destination We don’t support Segment’s Group or Screen event types; you can’t set up a subscription using these event types. Therefore, attempting to test against these events will result in an error.

The event tester page with a populated event and successful test
The event tester page with a populated event and successful test

Migrate to Destination Actions

If you already have a Segment Destination integration, and want to take advantage of anonymous events or other mapping functions, you can migrate to Destination Actions in Segment. You’ll need to set up Destination Actions first, and then turn your standard destination integration off, which may result in duplicate events.

  1. Set up your new Destination Action.
  2. In Segment, click Destinations and select your original Segment destination.
  3. Click the toggle to disable it.

You may receive duplicate events in the time after you set up your new destination action and before you disable the old destination.

Click the toggle to disable a destination
Click the toggle to disable a destination

Identify people

The Identify method corresponds to the Create or Update Person action (or any custom subscriptions you create to identify people in Segment’s method to identify people is 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 that person 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('customerio_id', {
      // the email belongs to the lead you identified in the previous step
      // so we'll assign an id value of "customerio_id" this person.
      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.

Unsubscribe 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 their own Suppression and Deletion tools. These tools are separate from’s methods to delete and suppress people.

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 person you suppressed and deleted in Segment is removed in

Anonymous Events

Segment generates an anonymousId trait for people that you haven’t identified with a userId. Events generated by unidentified people are passed to as “anonymous events”—events attributed to this anonymousId. If the anonymous event merge feature is turned on in your workspace (the default setting for new workspaces), automatically merges anonymous events with people when you identify them. This all happens automatically with the Segment Destination Actions integration.

Add and Update Devices

A standard identify call can add and update mobile devices. This might happen if a user logs into your service from inside your mobile app. In this case, you’re both identifying a person and associating a device with them.

However, there are also default Destination Actions to add, update, and delete devices based on track events. These actions are filtered by the event value.

  • Application Installed events add or update devices.
  • Application Opened events add or update devices.
  • Application Uninstalled events remove devices.

Here’s an example Application Installed event.

    "action": "track",
    "userId": "019mr8mf4r",
    "event": "Application Installed",
    "properties": {
        "version": "1.2.3",
        "build": 1234
    "context": {
        "device": {
            "token": "ff15bc0c20c4aa6cd50854ff165fd265c838e5405bfeb9571066395b8c9da449",
            "type": "ios"
Copied to clipboard!