Skip to main content
search_people is the widest surface in the API: twenty-three parameters, most of them exact-match. The difference between a good search and a wasted one is almost always which filter you reach for, not how many you stack.

​
Start with a free count

search_linkedin_profile accepts count_only: true, which returns the number of matching results without fetching data or charging tokens. Use it to size a search before committing to it.
Tokens are only charged when data is found and returned. A search that matches nothing costs nothing — but it still counts against your rate limit. See Rate Limits.

​
Probe with limit: 1 before you pull a page

count_only is only available on search_linkedin_profile. On search_people there is no free dry run — so the cheapest way to check that a search is actually returning the people you meant is to run it with limit: 1.
One record costs one search record against your fair use pool. The same query at limit: 25, walked five pages deep, costs 125 — and if a filter value was misspelt, a department/functional_area pair contradicted itself, or city matched a suburb you didn’t want, all 125 are spent on the wrong audience and can’t be refunded. Read three things off the single result before you widen:
  1. total — is the audience the size you expected? A total of 0 or 3 means a filter is wrong, not that the market is empty. total sits at the top level of the response, alongside results — not inside it. Over raw HTTP the body nests one level deeper, so the path is results.total.
  2. The record itself — does this person actually match your intent? Check title, seniority, location, and employer against what you asked for.
  3. business_email and business_email_risk_score — if you’re searching in order to email, confirm the emails are present and graded well enough to be worth pulling at volume.
Only when all three look right should you re-run with a larger limit and start paginating.
Search records are capped separately from enrichment records and are consumed per record returned, on a rolling 5-hour window. A single unchecked limit: 25 loop can burn a meaningful share of a plan’s pool before you notice the filters were wrong. See Rate Limits.

​
Filters are free precision

Search cost is driven by the free-text query, not by the filters attached to it. Two rules follow. Never send a bare query. Attaching country, seniority, or anything else costs nothing and sharply narrows the result set. A query-only call is the least precise shape available and no cheaper than a filtered one. Drop query entirely when filters can carry the whole intent. “VPs of sales at US software companies” is fully expressible as seniority, department, industry, and country — as a pure filter search it runs much faster than the same request phrased as free text.
This is about execution cost, not billing. Tokens are charged per record returned regardless of query shape — a cheaper query returns faster and puts less load on search capacity, but it doesn’t change what you’re charged.

​
If all you have is text, add a country

country is ~99% filled — the highest fill rate of any filter. Attaching it to a free-text search discards almost no legitimate matches while removing everything from other markets. It is the cheapest precision available, and the default filter to reach for when you have nothing else.

​
Put the right thing in query

query is a full-text search across full_name, first_name, last_name, company name, title (~85% filled), and headline (~65% filled). Multi-word queries distribute terms across fields — "John Smith" matches first_name: John and last_name: Smith rather than either alone. Naming a company in query gets it diluted across the name and title fields. Use company or company_domain to scope to an employer.

​
Search roles with title, not query

title filters on the job title field alone, which makes it the precise way to search by role. A role dropped into query is spread across names, company names, and the headline, so it matches loosely — query: "Account Executive" will also bring back Account Managers.
The match is analysed rather than literal, and how strict it is depends on the length of what you pass: That allowance is what keeps function words from breaking a match: "VP of Sales" still finds someone stored as "VP, Sales". Extra words in the stored title are always fine — "Account Executive" matches "Senior Account Executive, SMB". title and seniority answer different questions and combine well. Use seniority for the level, title for the role:
title is ~85% filled. The ~15% of profiles with no title on record can never match a title filter, no matter what you pass — so a title filter always trades some reach for its precision.

​
Know each filter’s fill rate

Every exact-match filter silently discards records where that field is empty. Stacking three sparse filters can cut a viable audience to nothing.
department and functional_area share the same underlying data, the same document counts, and the same values. Filtering on both narrows nothing and risks contradicting yourself — pick one.

​
Choose your industry granularity

Three filters describe industry at different resolutions. Pick the one that matches how specific your targeting actually is. naics_code works at any level of the hierarchy. A 2-digit sector is broad ("54" = Professional Services); a 6-digit code is surgical ("541120" = Offices of Notaries). Shorten the code to widen the net.

​
Get location right

country, state, and city all filter the person’s location and all require exact stored values.
  • Use full English names, not abbreviations — "Texas", not "TX".
  • "UK" and "HK" exist in the data as dirty values. Prefer "United Kingdom" and "Hong Kong".
  • City names repeat across regions. Combine with state or country to disambiguate — city: "Portland", state: "Oregon".
  • city matches the exact stored city, not its suburbs. For metro-area coverage, filter on state or country instead.

​
Target by company size without naming a company

employee_range and revenue_range on search_people filter on the person’s current employer. This finds people at companies of a given size or revenue without you having to supply a company at all.
Both use the same vocabulary as search_companies — eight employee bands and seven revenue bands, and nothing else. Older documentation mentioned "Small", "Mid-Market", "Enterprise", and "Unknown" for size, and finer revenue bands above "Above $50M"; those are retired and now return nothing.

​
Exclude what you don’t want

Six filters remove people instead of selecting them. Each takes a list, and each mirrors a filter you already know: exclude_company_domain is your suppression list — pass the accounts you already have and nobody from them appears:
The rest carve out segments. “US VPs, but not California, and no interns or entry-level”:
Exclude in the query, not after it. An excluded person is never returned, so they cost you no tokens and no search records. Pulling 25 results and discarding five yourself costs you all 25.
Exclusions narrow a search — they can’t be the whole search. At least one positive input is still required.
Exclusion only drops profiles that positively carry the value you list. industry and seniority are each ~60% filled, so the ~40% of profiles with nothing on record are never excluded by exclude_industry or exclude_seniority — they still come through. A missing value is not an excluded value.

​
Match exact strings exactly

Every non-query filter is an exact match. The most common failure is a near-miss on capitalisation or spacing:
  • "C Suite" has a space, not a hyphen
  • "Marketing & Advertising" uses an ampersand
  • "Medical & Health" uses an ampersand
  • "5001+" and "$500k - $1M" must match character for character
search_people results already include business_email and its business_email_risk_score. For contacts where the search returns an email, you don’t need a follow-up enrichment call. See Getting Valid Emails for what the grades mean.

​
Paginate deliberately

Results are ranked — a higher _score means a stronger match, so the first page is the best page. Every response carries a top-level total, the count of matching records across all pages (results.total in the raw HTTP body). Read it before paginating to decide whether the search is worth walking, then increment offset by your limit. The limit: 1 probe above gets you that total for the price of a single record.
total stops counting at 10,000, and pagination stops there too. A total of 10000 means at least 10,000 matches, not exactly 10,000 — don’t size a run off it. offset + limit can’t exceed 10,000 either, so no amount of paging reaches record 10,001. To pull a larger audience, split the search into narrower slices — by state, industry, employee_range, or seniority — and walk each slice separately.

Searching for Companies

Qualify accounts first, then find people at them.

Getting Valid Emails

Turn a contact into a deliverable address.