Passthrough segments

For users having their own CDP systems or segmentation systems, we give you the ability to express the link between one of your users and your own defined segments through the passthrough segments functionality.

❗️

Warning

Passthrough functionality is not enabled by default. Please contact your customer success representative if you want to use pass-through features.

Associate an user with an external segment

The process of linking a user to an external segment is done through qualifying or disqualifying users from the external segment through an event request in the upload events api

Example Qualify Event

This is when a user is associated with an external segment.

{
  "type": "passthrough",
  "action": "qualify",
  "identifiers": {
    "a_high_confidence_identifier": "a_user_id"
  },
  "data": {
    "audience_id": "audience_1", #this is the external segment name or id
    "ts": 1748851070 #this is the timestamp in seconds for when the event occured
  }
}

Example Disqualify Event

This is when a user leaves/gets disassociated with an external segment.

{
  "type": "passthrough",
  "action": "disqualify",
  "identifiers": {
    "a_high_confidence_identifier": "a_user_id"
  },
  "data": {
    "audience_id": "audience_1", #this is the external segment name or id
    "ts": 1748851070 #this is the timestamp in seconds for when the event occured
  }
}

📘

For CDPs or segmentation systems that are unable to disqualify users, we provide an alternative import feature.

❗️

Warning

Please note that for passthrough segments you must provide one and only one high confidence identifier in the identifiers section, as for those events we do not do any identity resolution and fully rely on your provided identifier to properly link the user to the segment.

Creating an external segment

Creating a passthrough segment that is accessible from the graphql api/segments requires the user to create the segment through the segments api as a passthrough segment

You can create or update an existing passthrough segment by sending the following request:

{
  "definition": {
    "external": {
      "external_audience_id": "external_id"
    }
  }
  "description": "Some description",
  "metadata": {}
}

Other api requests to the segments api remain unchanged.

GraphQL API

User membership evaluation

You can query if a user is part of a segment as with regular segments in graphql

query {
  customer(_a_high_confidence_identifier: "a_user_id") {
    audiences (subset: ["an_external_segment_id", "another_external_segment_id"]) {
  }
}

List segments

And you can also list all segments through the graphql api as with regular segments:

query {
  audiences {
    edges {
      node {
        name
        revision
        description
        is_ready # passthrough audiences will always be ready
        size # passthrough audience sizes will be null until we implement sizes
      }
    }
  }
}