Passthrough audiences

8 min

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 audiences through the passthrough audiences functionality.

Warning

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

Associate a user with an external audience

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

Example Qualify Event

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

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

{
  "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 audiences 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 audience that is accessible from the GraphQL API or audiences requires the user to create the audience through the segments API as a passthrough audience.

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

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

Additional API requests to the audiences API remain unchanged.

GraphQL API

User membership evaluation

You can query if a user is part of an audience, similar to regular segments in GraphQL.


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

List audiences

And you can also list all audiences through the GraphQL API, similar to regular audiences:


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
      }
    }
  }
}