Segments — Filters & Helpers

Filters define which clients are included in a segment. Multiple filters on a segment are combined with AND logic. This page documents the filter types and the endpoints for testing filters, unioning segments, and discovering custom-field names/values.

Auth: Bearer token. test-filters and union/client-ids resolve the workspace from the request body (workspace_id); the custom-field helpers resolve it from the workspace_id query parameter.

Filter Types Overview

Filter Type	Description
`all`	Match every pass in the workspace
`template`	Filter by pass template
`project`	Filter by project
`custom_field`	Filter by pass custom field values
`client_custom_field`	Filter by client-level custom field values
`wallet_balance`	Filter by wallet/points balance
`tier`	Filter by loyalty tier
`event_count`	Filter by event count in a time window
`event_sum`	Filter by sum of transaction amounts
`field_sum`	Filter by sum of field-change deltas
`event_recency`	Filter by time since last event

Each filter is { filter_type, filter_config } (with an optional id). The shapes below cover the most common configs.

Template Filter

Field	Type	Required	Description
`pass_template_ids`	`array<string (UUID)>`	Yes	Template identifiers to include (at least one)

json

{ "filter_type": "template", "filter_config": { "pass_template_ids": ["uuid-1", "uuid-2"] } }

Project Filter

Field	Type	Required	Description
`project_ids`	`array<string (UUID)>`	Yes	Project identifiers to include (at least one)

json

{ "filter_type": "project", "filter_config": { "project_ids": ["uuid-1", "uuid-2"] } }

Custom Field Filter

Field	Type	Required	Description
`custom_field_filters`	`object`	Yes	Map of field name → condition

Each condition is { operator, value }:

Operator	Description	Value Type
`_eq`	Equals	any
`_neq`	Not equals	any
`_gt` / `_gte` / `_lt` / `_lte`	Numeric comparisons	number
`_contains`	Contains substring	string
`_starts_with`	Starts with	string
`_ends_with`	Ends with	string
`_in`	In array	array
`_nin`	Not in array	array
`_null`	Is null / not null	boolean

json

{
  "filter_type": "custom_field",
  "filter_config": {
    "custom_field_filters": {
      "tier": { "operator": "_eq", "value": "Gold" },
      "points": { "operator": "_gte", "value": 1000 }
    }
  }
}

Event Count / Event Sum / Field Sum / Event Recency

These behavioral filters share a time-window model (day, week, month, quarter, year, all_time, or a custom_days / from_date+to_date range) and a comparison operator + value. Examples:

json

{ "filter_type": "event_count", "filter_config": { "event_category": "transaction", "event_types": ["purchase"], "operator": "_gte", "value": 5, "time_window": "month" } }

json

{ "filter_type": "event_sum", "filter_config": { "event_category": "transaction", "field": "amount", "operator": "_gte", "value": 500, "time_window": "quarter" } }

json

{ "filter_type": "field_sum", "filter_config": { "field_name": "points", "operator": "_gte", "value": 1000, "time_window": "year" } }

json

{ "filter_type": "event_recency", "filter_config": { "event_category": "engagement", "event_types": ["visit"], "operator": "not_within_days", "days": 30 } }

Test Filters

POST /wallethero-api/segments/test-filters

Evaluates a set of filters against the workspace without creating a segment. Returns matching clients, computed columns, and a tier breakdown. Registered before /segments/:id so test-filters is not parsed as a UUID.

Auth: Bearer token — workspace member (resolved from the workspace_id body field).

Request Body

Field	Type	Required	Default	Description
`workspace_id`	`string (UUID)`	Yes	—	Workspace identifier
`filters`	`SegmentFilter[]`	No	`[]`	Filters to evaluate
`limit`	`number`	No	`10`	Max sample clients to return (1–1000)

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/segments/test-filters" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "WORKSPACE_ID",
    "filters": [
      { "filter_type": "custom_field", "filter_config": { "custom_field_filters": { "tier": { "operator": "_eq", "value": "Gold" } } } }
    ],
    "limit": 10
  }'

Response (200)

json

{
  "data": {
    "clients": [ { "id": "client-1", "first_name": "Jane", "email": "[email protected]" } ],
    "passes": [],
    "total": 342,
    "computed_columns": [],
    "tier_breakdown": [
      { "tier_id": "tier-1", "tier_name": "Gold", "color": "#FFD700", "count": 342 }
    ]
  }
}

SDK

typescript

const result = await wh.segments.testFilters(
  "WORKSPACE_ID",
  [
    { filter_type: "custom_field", filter_config: { custom_field_filters: { tier: { operator: "_eq", value: "Gold" } } } },
  ],
  10,
);
console.log(`Matched ${result.total} clients`);

Union Segment Client IDs

POST /wallethero-api/segments/union/client-ids

Returns the deduplicated union of client IDs across multiple segments in one workspace. Useful for materializing a manual_client_ids list for a campaign that targets several segments. Registered before /segments/:id so union is not parsed as a UUID.

Auth: Bearer token — workspace member (resolved from the workspace_id body field).

Request Body

Field	Type	Required	Description
`workspace_id`	`string (UUID)`	Yes	Workspace identifier
`segment_ids`	`array<string (UUID)>`	Yes	1–50 segment IDs to union

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/segments/union/client-ids" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "workspace_id": "WORKSPACE_ID", "segment_ids": ["seg-1", "seg-2"] }'

Response (200)

json

{ "data": ["client-1", "client-2", "client-3"] }

SDK

typescript

const clientIds = await wh.segments.getClientIdsUnion("WORKSPACE_ID", ["seg-1", "seg-2"]);

List Custom Field Names

GET /wallethero-api/passes/custom-fields

Returns the distinct custom-field names used on passes in a workspace — useful for building dynamic custom_field filters.

Auth: Bearer token — workspace member (resolved from the workspace_id query parameter).

Query Parameters

Parameter	Type	Required	Description
`workspace_id`	`string (UUID)`	Yes	Workspace identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/passes/custom-fields?workspace_id=WORKSPACE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{ "data": ["tier", "points", "birthday", "favorite_store"] }

SDK

typescript

const names = await wh.segments.getCustomFieldNames("WORKSPACE_ID");

List Custom Field Values

GET /wallethero-api/passes/custom-fields/:fieldName/values

Returns distinct values for a specific custom field in a workspace, each with a count and a flag indicating whether the values look numeric.

Auth: Bearer token — workspace member (resolved from the workspace_id query parameter).

Path Parameters

Parameter	Type	Description
`fieldName`	`string`	Custom field name

Query Parameters

Parameter	Type	Required	Default	Description
`workspace_id`	`string (UUID)`	Yes	—	Workspace identifier
`limit`	`number`	No	`50`	Max distinct values to return (capped at 100)

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/passes/custom-fields/tier/values?workspace_id=WORKSPACE_ID&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": [
    { "value": "Gold", "count": 342, "isNumeric": false },
    { "value": "Silver", "count": 1100, "isNumeric": false }
  ]
}

SDK

typescript

const values = await wh.segments.getCustomFieldValues("WORKSPACE_ID", "tier", 50);

Combining Filters (Example)

typescript

const { data: segment } = await wh.segments.create({
  workspace_id: "WORKSPACE_ID",
  name: "Lapsed High Spenders",
  filters: [
    { filter_type: "custom_field", filter_config: { custom_field_filters: { tier: { operator: "_in", value: ["Gold", "Platinum"] } } } },
    { filter_type: "event_sum", filter_config: { event_category: "transaction", field: "amount", operator: "_gte", value: 500, time_window: "all_time" } },
    { filter_type: "event_recency", filter_config: { event_category: "engagement", event_types: ["visit"], operator: "not_within_days", days: 30 } },
  ],
});

Segments — Filters & Helpers ​

Filter Types Overview ​

Template Filter ​

Project Filter ​

Custom Field Filter ​

Event Count / Event Sum / Field Sum / Event Recency ​

Test Filters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Union Segment Client IDs ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

List Custom Field Names ​

Query Parameters ​

Example Request ​

Response (200) ​

SDK ​

List Custom Field Values ​

Path Parameters ​

Query Parameters ​

Example Request ​

Response (200) ​

SDK ​

Combining Filters (Example) ​

Segments — Filters & Helpers

Filter Types Overview

Template Filter

Project Filter

Custom Field Filter

Event Count / Event Sum / Field Sum / Event Recency

Test Filters

Request Body

Example Request

Response (200)

SDK

Union Segment Client IDs

Request Body

Example Request

Response (200)

SDK

List Custom Field Names

Query Parameters

Example Request

Response (200)

SDK

List Custom Field Values

Path Parameters

Query Parameters

Example Request

Response (200)

SDK

Combining Filters (Example)