Skip to content
LeadSonar LeadSonar Docs

Count leads

POST
/api/v1/leads/search

Cost: Free

Returns counts only and charges nothing. Two totals are reported because they measure different things: structured filters are counted upstream, while titles/keywords/department are applied per row and can only be sampled. Plan exports around estimated_total.

Try it

curl https://app.leadsonar.io/api/v1/leads/search \
  -H "X-API-Key: $LS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobTitles": ["Head of Sales"],
    "exactMatch": true,
    "industry": ["Software Development"],
    "companySize": ["51-200"],
    "country": ["US"]
  }'

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Lead Finder filters. Singular and plural spellings are both accepted (industry / industryNames).

object
industry
Array<string>
seniority
Array<string>
country

ISO country codes. The source is ~99.9% US.

Array<string>
companySize
Array<string>
revenue
Array<string>
department
Array<string>
jobTitles

Free text, whole-word matched against the job title.

Array<string>
includeKeywords

Matched against the company description, not the title.

Array<string>
excludeKeywords
Array<string>
maxPerCompany

Cap contacts per company.

integer
companyType

Company type, derived from each company’s industry (the source has no ownership field). Values OR together. Public (listed) company filtering is not available yet; sending “public” or any other value returns 400 with code COMPANY_TYPE_NOT_AVAILABLE or UNKNOWN_COMPANY_TYPE.

Array<string>
Allowed values: private government nonprofit education
exactMatch

Match jobTitles (and keywords) as whole words. Without it titles match as substrings, so “CFO” can hit unrelated titles. The app always sends true; set it yourself.

boolean
excludeTitles

Drop anyone whose job title contains any of these words, e.g. [“intern”, “assistant”].

Array<string>
Example
{
  "jobTitles": ["Head of Sales"],
  "exactMatch": true,
  "industry": ["Software Development"],
  "companySize": ["51-200"],
  "country": ["US"]
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Match counts

object
firmographic_total

Structured filters only (industry, size, country, revenue), counted upstream.

integer
firmographic_is_exact
boolean
estimated_total

After per-row matching (titles, keywords, department, seniority). PLAN EXPORTS AROUND THIS NUMBER.

integer
basis
string
Allowed values: sampled exact
note
string
narrowed_by

Which filter collapsed the result, when one did.

string
nullable
keywords

What each include-keyword cost, per term.

object
filters

The filters as the server understood them — check this when a count looks wrong.

object
key
additional properties
any
Example
{
  "firmographic_total": 179984,
  "firmographic_is_exact": true,
  "estimated_total": 607,
  "basis": "sampled",
  "note": "estimated_total is sampled: keyword/role/department filters are applied per row and cannot be counted upstream. Plan exports around estimated_total.",
  "narrowed_by": null,
  "keywords": null,
  "filters": {
    "industryNames": ["Software Development"],
    "countryCodes": ["US"],
    "companySizes": ["51-200"],
    "jobTitles": ["Head of Sales"],
    "exactMatch": true,
    "matchAny": false
  }
}

502

Section titled “502 ”

Lead source unavailable (LEADS_SOURCE_DOWN)

object
error
required

Human-readable error message

string
message

Additional details

string