Lead database

Search every contact with its outreach status across campaigns, role, and company, roll contacts up by company, and measure ICP coverage.

The lead database reads the workspace's contacts with fields worked out from what each contact already holds and from every campaign that touched them. The fields and their rules are explained in the lead database guide.

Every route is a read-only POST, so filters travel as JSON and a retry is naturally safe. Auth: Scope READ_CONTACTS · Org permission view_contacts. Errors follow the standard envelope in error codes.

Filters

Every route takes the same filter body:

Field	Type	Description
`conditions`	array	Segment conditions, validated by the same rules as a segment. The lead fields are `outreach_status` (`fresh`, `enrolled`, `contacted`, `replied`, `positive`, `meeting`, `bounced`, `unsubscribed`), `seniority`, `department`, `job_title`, `company_domain`, and `emailed_by_campaign`. `GET /segments/fields` lists every field with its operators and options.
`match`	string	`all` (default) or `any`.
`segment_id`	UUID	Only members of this saved segment. An unknown id matches nothing.
`q`	string	Text search over name, email, and company, at most 200 characters.

A bad filter returns 400 invalid_lead_query.

{
  "conditions": [
    { "field": "seniority", "operator": "in", "values": ["vp", "head", "director"] },
    { "field": "department", "operator": "in", "values": ["sales"] },
    { "field": "emailed_by_campaign", "operator": "not_in", "values": ["b1f2c3d4-0000-0000-0000-000000000001"] }
  ]
}

Search people

POST /lead-database/people

Takes the filter plus sort (last_contacted by default, created, name, emails_received, or company), limit (1 to 200, default 50), and cursor (the next_cursor of the previous page). An unsupported value returns 400 invalid_sort, invalid_limit, or invalid_cursor.

{
  "data": [
    {
      "id": "c0ffee00-0000-0000-0000-000000000002",
      "email": "ada@acme.io",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "company": "Acme",
      "company_domain": "acme.io",
      "job_title": "VP of Sales",
      "seniority": "vp",
      "department": "sales",
      "esp_provider": "gmail",
      "verification_status": "valid",
      "outreach_status": "contacted",
      "campaigns": 2,
      "emails_received": 4,
      "last_contacted_at": "2026-09-28T14:02:11Z",
      "last_replied_at": null,
      "created_at": "2026-06-11T09:00:00Z"
    }
  ],
  "pagination": { "next_cursor": "eyJvIjo1MH0", "has_more": true }
}

Search companies

POST /lead-database/companies

Groups the matching people by company_domain; people with no company domain are left out. Takes the filter plus sort (people by default, fresh, contacted, positive, last_contacted, or domain), limit, and cursor. Each row carries domain, name (the most common company name), people, contacted, replied, positive, meetings, bounced, unsubscribed, fresh, last_contacted_at, and esp_provider (the most common one), in the same data and pagination shape.

Get coverage

POST /lead-database/coverage

Takes the filter and returns how much of that audience outreach has reached:

{
  "total": 12400,
  "contacted": 4712,
  "contacted_90d": 1980,
  "enrolled": 640,
  "replied": 301,
  "positive": 88,
  "meetings": 21,
  "bounced": 97,
  "unsubscribed": 45,
  "fresh": 7048,
  "fresh_reachable": 6611,
  "companies": 2310,
  "companies_contacted": 1402,
  "contacted_share": 0.38
}

contacted counts everyone who received at least one campaign email. fresh_reachable is fresh without invalid addresses and anything on the suppression list. contacted_share is null when nothing matches.

POST /lead-database/facets

Takes the filter and counts the audience by outreach_status, seniority, department, esp_provider (unknown when not resolved), and verification_status, each a list of { "key", "count" }.

Export people

POST /lead-database/export

Takes the filter plus sort and returns text/csv with the people fields as columns, at most 50,000 rows. X-Total-Rows carries the row count. Cells that a spreadsheet would read as a formula are prefixed with '. Every export is recorded in the audit log.