Skip to main content
GET
Preview a filter

Authorizations

X-API-Key
string
header
required

API key with format cs_live_xxx

Query Parameters

sample_size
integer
default:10

Sample rows to return

Required range: 0 <= x <= 50
signal
enum<string>[] | null

Match any of these engagement signals

Engagement signal for a directory contact.

Materialised onto contacts.signal by the contact rollup job so the directory can filter and sort on it without touching leads. Derived from the contact's campaign memberships in strict precedence order -- the first match wins:

A non-NULL contacts.signal_override always wins over the derived value, so a manually pinned signal is never clobbered by the job.

Mirrors the contactsignal Postgres enum created in migration 20260826_0001_add_contact_directory.py. Keep in sync.

Available options:
NEVER_CONTACTED,
CONTACTED,
ENGAGED,
HOT_LEAD,
BOUNCED,
UNSUBSCRIBED
tag_ids
string<uuid>[] | null

Match contacts carrying any of these tags

is_unsubscribed
boolean | null

Filter on team-level suppression

is_bounced
boolean | null

Filter on whether any membership bounced

source_type
enum<string>[] | null

Match any of these acquisition sources

How a contact first entered the directory.

Stored as a plain string column (not a Postgres enum) to match the existing lead_batches.source_type convention; this class is the canonical set of allowed values and is enforced by a CHECK constraint.

Available options:
CSV,
MANUAL,
COPY,
EXTERNAL_EMAIL,
API
source_name
string | null

Exact origin name, e.g. the uploaded file name

campaign_id
string<uuid> | null

Only contacts with a membership in this campaign

not_in_campaign_id
string<uuid> | null

Exclude contacts already in this campaign

last_touch_after
string<date-time> | null

Last outbound contact at or after this time

last_touch_before
string<date-time> | null

Last outbound contact strictly before this time

has_replied
boolean | null

Filter on whether the contact ever replied

has_opened
boolean | null

Filter on whether the contact ever opened

search
string | null

Substring match across email, name and company

Response

Preview evaluated

Outcome of evaluating an unsaved filter.

message
string
required
total
integer
required
sample
ContactResponse · object[]
required
success
boolean
default:true