SegmentsService

Define audience segments for targeting campaigns.

Methods

Method	Description
list(options?)	List all segments
get(id)	Get a single segment
create(data)	Create a segment
update(id, data)	Update a segment
delete(id)	Delete a segment
testFilters(data)	Test filter criteria
calculate(id)	Calculate segment size
preview(id, options?)	Preview segment members
duplicate(id, options?)	Duplicate a segment

create()

Create a segment with filter criteria.

const segment = await client.segments.create({
  workspace_id: 'workspace-uuid',
  name: 'High Value Gold Members',
  description: 'Gold+ members with $500+ lifetime spend',
  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'
      }
    }
  ]
});

testFilters()

Test filter criteria without creating a segment.

const result = await client.segments.testFilters({
  workspace_id: 'workspace-uuid',
  filters: [
    {
      filter_type: 'event_recency',
      filter_config: {
        event_category: 'activity',
        event_types: ['visit'],
        operator: 'not_within_days',
        days: 30
      }
    }
  ],
  limit: 10
});

console.log(`Found ${result.total} lapsed users`);
console.log('Sample:', result.passes.map(p => p.full_name));

calculate()

Get the current size of a segment.

const size = await client.segments.calculate('segment-uuid');
console.log(`Segment has ${size.total} members`);

preview()

Preview segment members.

const preview = await client.segments.preview('segment-uuid', { limit: 50 });
console.log(`Showing ${preview.length} of segment members`);

Filter Types

// Filter by template
{ filter_type: 'template', filter_config: { pass_template_ids: ['uuid'] } }

// Filter by project
{ filter_type: 'project', filter_config: { project_ids: ['uuid'] } }

// Filter by custom field
{
  filter_type: 'custom_field',
  filter_config: {
    custom_field_filters: {
      tier: { operator: '_eq', value: 'Gold' },
      points: { operator: '_gte', value: 1000 }
    }
  }
}

// Filter by event count
{
  filter_type: 'event_count',
  filter_config: {
    event_category: 'transaction',
    event_types: ['purchase'],
    operator: '_gte',
    value: 5,
    time_window: 'month'
  }
}

// Filter by transaction sum
{
  filter_type: 'event_sum',
  filter_config: {
    event_category: 'transaction',
    field: 'amount',
    operator: '_gte',
    value: 100,
    time_window: 'quarter'
  }
}

// Filter by event recency
{
  filter_type: 'event_recency',
  filter_config: {
    event_category: 'activity',
    event_types: ['visit'],
    operator: 'within_days',
    days: 7
  }
}