Skip to main content
GET
Search the contact directory

Authorizations

X-API-Key
string
header
required

API key with format cs_live_xxx

Query Parameters

list_id
string<uuid> | null

Narrow to the members of a saved list

page
integer
default:1

Page number

Required range: x >= 1
limit
integer
default:20

Items per page

Required range: 1 <= x <= 100
sort_by
string
default:created_at

Sort column

sort_desc
boolean
default:true

Sort descending

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

Contacts retrieved successfully

Response for a directory search.

Not to be confused with ContactListResponse from the shared schema module, which describes one saved segment.

message
string
required
contacts
ContactResponse · object[]
required
pagination
PaginationMeta · object
required

Pagination metadata schema.

success
boolean
default:true