Searching Contacts And Companies

Overview

Use these endpoints when you need more than the basic list query params:

POST /v1/contacts/search
POST /v1/companies/search

The search endpoints support:

search for full-text matching
include for positive filters
exclude for negative filters
page and pageSize for pagination
fields on contact search when you want extra contact/company-backed fields returned

Start With The Fields Endpoints

Treat the fields endpoints as the schema source of truth for filtering:

GET /v1/contacts/fields
GET /v1/companies/fields

Each field object tells you:

id: the exact key to use in include, exclude, and contact fields
label: the human-readable name
dataType: how to shape the filter value
fieldType: whether the field is standard, AI, CRM, formula, or empty

For contact search, GET /v1/contacts/fields already includes valid company-backed field IDs such as companyName, so start there first. If your workspace exposes scoring fields like icpScore, scoreBand, or custom AI/formula fields, use the exact id returned by the fields endpoint before adding them to search filters.

Enrichment-Backed Company Fields

GET /v1/companies/fields also returns fields that come from enrichment providers rather than the base company record — ecommerce store data (Store Leads), web traffic (Similarweb), funding (fundraising data), job openings, headcount, and technologies. They are used the same way: request them in fields, or filter on them in include. Ecommerce examples:

ecommerceStoreEstimatedSales and ecommerceStoreEstimatedSalesYearly — estimated monthly / yearly sales (GMV)
ecommerceStoreProductCount, ecommerceStoreAvgPrice
ecommerceStoreEstimatedVisits, ecommerceStoreEstimatedPageViews
ecommerceStoreTrustpilotRating, ecommerceStoreTrustpilotReviewCount
ecommerceStoresPlatform, ecommerceStoresShippingCarriers, ecommerceStoresShipsToCountries
ecommerceStores — the full per-store payload, including the installed technology stack

GET /v1/companies/14990284?fields=ecommerceStoreEstimatedSales,ecommerceStoresPlatform,ecommerceStores

Values are only present for companies that have been enriched by the matching provider.

Important Filters First

These are the highest-signal filters to reach for first:

id If you already know a single record ID, prefer GET /v1/contacts/{contactId} or GET /v1/companies/{companyId}. Use id inside search when you need to combine exact IDs with other filters.
leadsGroup or companyGroup List IDs for contact lists or company lists.
campaigns Campaign IDs when you want outreach-related slices.
isInCRM or isCompanyInCRM CRM presence filters.
leadsCount or numberOfEmployees Good first-pass sizing filters for companies and account selection.
Workspace scoring fields like icpScore Use only after confirming the field exists in /fields.
contactTags or companyTags Tag IDs from GET /v1/contacts/tags or GET /v1/companies/tags, with "" meaning no tag. Contact search accepts contactTags and company search accepts companyTags. See Contact and company tags.

Filter Value Schema

include and exclude are plain JSON objects whose keys are special filter names or field IDs from /fields. Use these value shapes:

Field type	Value shape	Example
Text / select / formula / AI / CRM field	Array of exact values	`"jobTitle": ["CEO", "Founder"]`
Numeric field	Two-item min/max range array	`"numberOfEmployees": ["50", "500"]`
Boolean field	One-item boolean array	`"isInCRM": [true]`
Timestamp field	Object with `startDate` and `endDate`	`"lastActivityAtCRM": { "startDate": "2026-01-01", "endDate": "2026-01-31" }`
Empty value match	Include an empty string in the array	`"professionalEmail": [""]`

Notes:

Range filters are inclusive.
You can leave one side open for numeric ranges, for example ["80", ""].
Contact search also accepts company-backed field IDs in include, exclude, and fields.

Contact Search Examples

Contact list ID + CRM presence

{
  "page": 1,
  "pageSize": 25,
  "search": "growth",
  "fields": ["firstName", "lastName", "jobTitle", "companyName", "professionalEmail"],
  "include": {
    "leadsGroup": [123],
    "isInCRM": [true]
  }
}

Contact IDs + company-backed filters

{
  "page": 1,
  "pageSize": 25,
  "include": {
    "id": [101, 205],
    "companyName": ["Stripe", "HubSpot"],
    "industry": ["Software"],
    "numberOfEmployees": ["50", "500"]
  },
  "exclude": {
    "campaigns": [77]
  }
}

Workspace scoring field

Replace icpScore with the exact scoring field ID from GET /v1/contacts/fields.

{
  "page": 1,
  "pageSize": 25,
  "include": {
    "leadsGroup": [123],
    "icpScore": ["80", "100"]
  }
}

Company Search Examples

Company list ID + employee range

{
  "page": 1,
  "pageSize": 25,
  "search": "analytics",
  "include": {
    "companyGroup": [42],
    "industry": ["Software"],
    "numberOfEmployees": ["50", "500"]
  }
}

Company IDs + lead count + CRM presence

{
  "page": 1,
  "pageSize": 25,
  "include": {
    "id": [101, 205],
    "leadsCount": ["5", "50"],
    "isCompanyInCRM": [true]
  },
  "exclude": {
    "campaigns": [88]
  }
}

Workspace scoring field

Replace scoreBand with the exact scoring field ID from GET /v1/companies/fields.

{
  "page": 1,
  "pageSize": 25,
  "include": {
    "companyGroup": [42],
    "scoreBand": ["A"]
  }
}

Reference Endpoints

Contact fields: GET /v1/contacts/fields
Company fields: GET /v1/companies/fields
Contact search: POST /v1/contacts/search
Company search: POST /v1/companies/search

​Overview

​Start With The Fields Endpoints

​Enrichment-Backed Company Fields

​Important Filters First

​Filter Value Schema

​Contact Search Examples

​Contact list ID + CRM presence

​Contact IDs + company-backed filters

​Workspace scoring field

​Company Search Examples

​Company list ID + employee range

​Company IDs + lead count + CRM presence

​Workspace scoring field

​Reference Endpoints

Overview

Start With The Fields Endpoints

Enrichment-Backed Company Fields

Important Filters First

Filter Value Schema

Contact Search Examples

Contact list ID + CRM presence

Contact IDs + company-backed filters

Workspace scoring field

Company Search Examples

Company list ID + employee range

Company IDs + lead count + CRM presence

Workspace scoring field

Reference Endpoints