Skip to main content
GET
List contacts

Authorizations

Authorization
string
header
required

An org API key: Authorization: Bearer oak_….

Query Parameters

limit
integer
default:50
Required range: 1 <= x <= 200
cursor
string | null
q
string | null
country
string[] | null
origin
enum<string>[] | null

Top-level acquisition category — how a contact entered the CRM.

Set once at first touch and never overwritten: a contact who joins the waitlist (WEB) and later messages on WhatsApp keeps WEB; the channel they messaged on lives on their ContactHandle, not here. The category is a fixed, platform-owned vocabulary so analytics roll-ups, the AI prompt, and inbound auto-assignment stay stable across orgs. The specific named source within a category (e.g. "Waitlist", "SaaStr 2026", "WhatsApp") is org-customizable — see the contact_sub_origins table. NULL for legacy contacts whose origin predates this field. Replaces the old conversational- only ContactSource (WHATSAPP/INSTAGRAM/MESSENGER), which collapsed acquisition and channel into one field.

Available options:
SOCIAL,
ADS,
WEB,
EVENT,
REFERRAL,
OUTBOUND,
IMPORT,
MANUAL,
API,
OTHER
funnel_stage_ids
string[] | null
owner_id
string[] | null
created_from
string<date> | null
created_to
string<date> | null
property_filter
string[] | null
sort
enum<string>
default:recent

Ordering applied to GET /contacts.

RECENT is the default (updated_at DESC, id DESC). The name / country / city / origin sorts are ASC with NULLS LAST so contacts missing the sorted column pool at the bottom rather than polluting the top.

Available options:
recent,
name,
country,
city,
origin
sort_dir
enum<string> | null

Direction for the active sort, toggled by the toolbar's asc/desc button. Omitted → per-sort default (time sorts newest-first / DESC; the text + enum sorts A→Z / ASC).

Available options:
asc,
desc

Response

Successful Response

items
PublicContact · object[]
required
next_cursor
string | null
required
total_count
integer | null