Skip to main content

​
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.

​
Important Filters First

These are the highest-signal filters to reach for first:
  1. 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.
  2. leadsGroup or companyGroup List IDs for contact lists or company lists.
  3. campaigns Campaign IDs when you want outreach-related slices.
  4. isInCRM or isCompanyInCRM CRM presence filters.
  5. leadsCount or numberOfEmployees Good first-pass sizing filters for companies and account selection.
  6. Workspace scoring fields like icpScore Use only after confirming the field exists in /fields.

​
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 typeValue shapeExample
Text / select / formula / AI / CRM fieldArray of exact values"jobTitle": ["CEO", "Founder"]
Numeric fieldTwo-item min/max range array"numberOfEmployees": ["50", "500"]
Boolean fieldOne-item boolean array"isInCRM": [true]
Timestamp fieldObject with startDate and endDate"lastActivityAtCRM": { "startDate": "2026-01-01", "endDate": "2026-01-31" }
Empty value matchInclude 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