Audiences API

Audiences are named segmentation queries built on top of a parent entity model. They use a visual filter tree to define membership criteria based on properties, traits, relationships, events, and other audiences.

Endpoints

Method	Path	Description
`GET`	`/api/v1/workspaces/{id}/audiences`	List all audiences
`POST`	`/api/v1/workspaces/{id}/audiences`	Create an audience
`GET`	`/api/v1/workspaces/{id}/audiences/{audId}`	Get an audience
`PUT`	`/api/v1/workspaces/{id}/audiences/{audId}`	Update an audience
`DELETE`	`/api/v1/workspaces/{id}/audiences/{audId}`	Delete an audience
`POST`	`/api/v1/workspaces/{id}/audiences/{audId}/estimate`	Estimate audience size
`GET`	`/api/v1/workspaces/{id}/audiences/{audId}/preview`	Preview audience members
`GET`	`/api/v1/workspaces/{id}/models/{modelId}/audiences`	List audiences by model
`POST`	`/api/v1/workspaces/{id}/models/{modelId}/estimate-filter`	Estimate filter count

List Audiences

GET /api/v1/workspaces/{id}/audiences

Returns all audiences in the workspace.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "660e8400-e29b-41d4-a716-446655440000",
    "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
    "name": "High-Value Customers",
    "description": "Customers with lifetime value over $1000",
    "filter_tree": {
      "type": "and",
      "children": [
        {
          "type": "condition",
          "condition_type": "property",
          "column": "lifetime_value",
          "operator": "greater_than",
          "value": 1000
        }
      ]
    },
    "estimated_size": 4250,
    "estimated_at": "2024-01-15T15:00:00Z",
    "status": "active",
    "status_error": "",
    "identity_graph_id": null,
    "created_by": "880e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Example

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces/{id}/audiences \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Create Audience

POST /api/v1/workspaces/{id}/audiences

Creates a new audience with a filter tree definition.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name
`description`	string	No	Description
`parent_model_id`	string (UUID)	Yes	Parent entity model to segment
`filter_tree`	object	Yes	Recursive filter tree definition
`identity_graph_id`	string (UUID)	No	Identity graph for cross-model resolution

Filter Tree Structure

The filter tree is a recursive JSON structure that supports boolean logic (and, or, not) and multiple condition types.

Group Nodes

{
  "type": "and",
  "children": [...]
}

Type	Description
`and`	All children must match
`or`	At least one child must match
`not`	Negates the child condition

Property Condition

Filters on a column of the parent model.

{
  "type": "condition",
  "condition_type": "property",
  "column": "lifetime_value",
  "operator": "greater_than",
  "value": 1000
}

Trait Condition

Filters on a computed trait value.

{
  "type": "condition",
  "condition_type": "trait",
  "trait_id": "550e8400-e29b-41d4-a716-446655440000",
  "operator": "greater_than",
  "value": 5
}

Relation Condition

Filters based on related model records, with optional nested filters.

{
  "type": "condition",
  "condition_type": "relation",
  "relationship_id": "660e8400-e29b-41d4-a716-446655440000",
  "quantifier": "any",
  "count_operator": "at_least",
  "count_value": 1,
  "filters": {
    "type": "and",
    "children": [
      {
        "type": "condition",
        "condition_type": "property",
        "column": "category",
        "operator": "equals",
        "value": "electronics"
      }
    ]
  }
}

Event Condition

Filters based on event occurrences with time windows.

{
  "type": "condition",
  "condition_type": "event",
  "relationship_id": "770e8400-e29b-41d4-a716-446655440000",
  "count_operator": "at_least",
  "count_value": 3,
  "time_window": {
    "type": "within",
    "value": 30,
    "unit": "days"
  }
}

Audience Condition

Filters based on membership in another audience.

{
  "type": "condition",
  "condition_type": "audience",
  "audience_id": "880e8400-e29b-41d4-a716-446655440000",
  "operator": "is_member"
}

Operators

Operator	Applicable Types	Description
`equals`	text, number	Exact match
`not_equals`	text, number	Not equal
`greater_than`	number, timestamp	Greater than
`less_than`	number, timestamp	Less than
`greater_than_or_equal`	number, timestamp	Greater than or equal
`less_than_or_equal`	number, timestamp	Less than or equal
`contains`	text	Substring match
`not_contains`	text	Does not contain
`starts_with`	text	Prefix match
`ends_with`	text	Suffix match
`is_null`	any	Value is null
`is_not_null`	any	Value is not null
`in`	text, number	Value is in list
`not_in`	text, number	Value is not in list
`between`	number, timestamp	Value is between two bounds
`is_member`	audience	Member of audience
`is_not_member`	audience	Not a member of audience

Count Operators (for relation/event conditions)

Operator	Description
`at_least`	Count >= value
`at_most`	Count <= value
`exactly`	Count == value
`between`	Count between value and value2

Time Window (for event conditions)

Field	Type	Description
`type`	string	`within`, `not_within`, `before`, `after`, `between`
`value`	integer	Time amount
`unit`	string	`hours`, `days`, `weeks`, `months`

Full Example

curl -X POST https://your-instance.signalsmith.io/api/v1/workspaces/{id}/audiences \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value Recent Buyers",
    "description": "Customers with LTV > $1000 who purchased in the last 30 days",
    "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
    "filter_tree": {
      "type": "and",
      "children": [
        {
          "type": "condition",
          "condition_type": "property",
          "column": "lifetime_value",
          "operator": "greater_than",
          "value": 1000
        },
        {
          "type": "condition",
          "condition_type": "event",
          "relationship_id": "990e8400-e29b-41d4-a716-446655440000",
          "count_operator": "at_least",
          "count_value": 1,
          "time_window": {
            "type": "within",
            "value": 30,
            "unit": "days"
          }
        }
      ]
    }
  }'

Get Audience

GET /api/v1/workspaces/{id}/audiences/{audId}

Returns a single audience by ID.

Example

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces/{id}/audiences/{audId} \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Update Audience

PUT /api/v1/workspaces/{id}/audiences/{audId}

Updates an existing audience definition.

Request Body

Same fields as create. Only include fields you want to change.

Delete Audience

DELETE /api/v1/workspaces/{id}/audiences/{audId}

Deletes an audience. Cannot be deleted if active audience syncs reference it.

Response

{
  "status": "deleted"
}

Estimate Audience Size

POST /api/v1/workspaces/{id}/audiences/{audId}/estimate

Runs the audience’s filter query against the warehouse to count matching records. The result is saved to the audience’s estimated_size and estimated_at fields.

Response

{
  "estimated_size": 4250,
  "estimated_at": "2024-01-15T15:00:00Z"
}

Example

curl -X POST https://your-instance.signalsmith.io/api/v1/workspaces/{id}/audiences/{audId}/estimate \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Preview Audience Members

GET /api/v1/workspaces/{id}/audiences/{audId}/preview

Returns a sample of records that match the audience’s filter criteria.

Response

{
  "columns": [
    {"name": "customer_id", "type": "VARCHAR", "nullable": false},
    {"name": "email", "type": "VARCHAR", "nullable": true}
  ],
  "rows": [
    {"customer_id": "C001", "email": "alice@example.com"},
    {"customer_id": "C002", "email": "bob@example.com"}
  ]
}

List Audiences by Model

GET /api/v1/workspaces/{id}/models/{modelId}/audiences

Returns all audiences attached to a specific parent model.

Estimate Filter

POST /api/v1/workspaces/{id}/models/{modelId}/estimate-filter

Estimates the count of matching records for an ad-hoc filter tree without creating an audience. Useful for the audience builder UI to show real-time size estimates.

Request Body

Field	Type	Required	Description
`filter_tree`	object	Yes	Filter tree to evaluate

Response

{
  "estimated_size": 3200
}

Audience Object

Field	Type	Description
`id`	string (UUID)	Unique identifier
`workspace_id`	string (UUID)	Owning workspace
`parent_model_id`	string (UUID)	Parent entity model
`name`	string	Display name
`description`	string	Description
`filter_tree`	object	Recursive filter tree definition
`estimated_size`	integer or null	Last estimated member count
`estimated_at`	string (ISO 8601) or null	When size was last estimated
`status`	string	`draft`, `active`, `archived`, or `error`
`status_error`	string	Error message when status is `error`
`identity_graph_id`	string (UUID) or null	Optional identity graph for cross-model resolution
`created_by`	string (UUID)	Account that created the audience
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Traits Audience Syncs