Find people at the right company
Use employer domains, title filters and current-role evidence to build a better people list, then find emails only for the profiles you need.
This guide is for agents and developers building a people list with people.search: which route answers, how to name the employer, how to page through a long list, how to preview before paying for emails, and how to budget. For a known company, start with its website domain and the job titles you need: a company name alone can refer to several businesses.
Start with qualified companies
If you only have an ideal customer profile, discover candidate company domains first. Check the required industry, company size, technologies and geography against supporting data before searching for their people. A generic company search does not prove a company uses a particular tool or meets a size threshold. Keep those requirements when changing data sources; leave an unconfirmed criterion as unknown.
Three routes
| Route | What it returns | Catalog price |
|---|---|---|
Lead database (icypeas) |
Name, headline, location, current title, company, company domain and LinkedIn URL. No email. Up to 200 people a call. | $0.001485 a call plus $0.000277 a person returned |
Known-company database (apollo) |
A known company's people, with the work email when one is on file. Up to 25 a call. | $0.0312 a person returned |
Live LinkedIn search (apify) |
Name, headline, location, the current role at the requested employer and every other current position, employer identity checked. No email. | $0.13 a page of up to 25 plus $0.0052 a full profile |
Prices on this page are catalog prices, which start at the Scale plan rate; inspect returns your workspace's exact price.
On automatic routing the router tries the routes that can take your input, cheapest quote for this input first, and moves to the next one when a route finds nobody or fails, within max_cost. The lead database almost always quotes lowest, so it answers first. The other two follow in the order of their quotes: the known-company database is priced per person and the LinkedIn search per page of 25, so above a handful of people the LinkedIn route comes first.
The lead database is a database, not a live search. It cannot combine titles with seniority, does not take company_headcount ranges with a gap, and cannot reveal person_ids. Those searches, and the ones it finds nobody for, go to the next route your max_cost admits.
To get a known company's people with their work email in one call, set routing.prefer to apollo: it runs first, and the other routes stay behind it if it finds nobody. That route searches people at known companies (a domain, or at most 3 company names, with a limit of 25 or less) or reveals people from preview IDs; it does not serve a broad search without employer names or domains. routing.provider: "apollo" pins it instead: a pinned route runs alone, and a miss there ends the run, unbilled.
Start with a domain and specific titles
Inspect the capability before running it:
curl https://api.routergrowth.com/v1/inspect \
-H "Authorization: Bearer $ROUTERGROWTH_API_KEY" \
-H "Content-Type: application/json" \
-d '{"capability":"people.search"}'
Then search one company. This example uses a small limit to find technical leaders:
curl https://api.routergrowth.com/v1/run \
-H "Authorization: Bearer $ROUTERGROWTH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"capability": "people.search",
"input": {
"companies": ["Microsoft"],
"company_domains": ["microsoft.com"],
"titles": ["Chief Technology Officer", "VP Engineering"],
"detail": "full",
"limit": 5
},
"routing": {"provider": "auto", "allow_fallback": true, "max_cost": "0.25"},
"wait_seconds": 120
}'
max_cost is a spending ceiling, not the expected charge: take yours from inspect (see budget), not from this example. If the response is 202, poll the returned run ID with GET /v1/runs/{run_id}?wait=60; do not submit the search again. See Run and Runs.
On auto routing this search runs on the lead database: the rows come back without emails, for well under a cent. Find the emails afterwards with contact.find, or set "prefer": "apollo" in routing to get the work emails with the people, billed per person returned.
For a broader employee list, raise limit only as far as you will use the results. Keep the employer filter and add titles, seniority or locations when relevant. Without title filters, a company search can return engineers, recruiters, interns and advisors; it is not automatically a decision-maker list.
Let the router select eligible providers
Use routing.provider: "auto" unless you deliberately need one provider. Pinning apollo or any other provider disables cross-provider fallback, even if allow_fallback is true; routing.prefer tries one provider first and keeps the others behind it. Raw endpoints always require their provider and never fall back.
Automatic routing still respects max_cost: a route whose quote for this input is above the cap is skipped, so a cap sized for the lead database ends the waterfall there. A company-constrained LinkedIn search pays a whole page plus an employer lookup whatever the limit, so at a small limit it needs the largest cap. Read the run's hints, error and attempts before retrying. On an unbilled no-match or provider failure, the error names the routes the cap kept out and the cap that admits the cheapest of them, and a no-match also carries a next_steps rerun at the cap that lets every route try. Review that cost against your budget; a higher cap does not guarantee a result.
Include equivalent title spellings in the first query, for example "VP Engineering" and "Vice President of Engineering". Adding directors broadens the seniority target; do that only if directors fit your requirements.
Choose the employer precisely
| Input | Best use |
|---|---|
company_ |
The company's actual website domain, such as microsoft.. Preferred when known. |
companies plus company_ |
A company name or LinkedIn company URL plus its website domain. If supplying several, pair the two arrays in the same order for the LinkedIn route. |
A LinkedIn company URL in companies |
The exact company page, especially when a name is ambiguous. Add its domain when known. |
A name in companies alone |
When you do not yet know the domain or company page. Ambiguous or unresolved employers may return no match. |
Start with one company per request so it is easy to review the results and diagnose misses. A paired request for two employers looks like:
{
"companies": ["Microsoft", "Salesforce"],
"company_domains": ["microsoft.com", "salesforce.com"],
"titles": ["Chief Technology Officer"],
"limit": 5
}
Domains identify the employer; locations restrict the people. Adding a headquarters city can accidentally exclude remote staff, so use a location only when it matters to your search.
Read past the first page
A lead-database search returns up to 200 people a call. Its result carries total (how many people match the filters), has_more and next_cursor. To walk the full list, run the same input again with "cursor" set to the previous next_cursor, and stop when next_cursor is null:
{
"capability": "people.search",
"input": {"company_domains": ["example.gov"], "limit": 200, "cursor": "cur_Qm9b3sJx0aR2Lw5t"},
"routing": {"provider": "auto", "max_cost": "0.10"}
}
Each page is a separate run, billed for the people it returns; no person appears on two pages. A cursor is short, belongs to your workspace and is kept for 7 days. Keep the filters unchanged: a cursor from other filters, or one that does not parse, fails with invalid_cursor before routing and charges nothing. limit may change between pages. Only the lead database pages, so a run with a cursor stays on it (routing.provider must be auto or icypeas) and never falls back to a route that would sell the first page again. To retry a page safely, send it with an Idempotency-Key: a replay returns the original run with Idempotent-Replay: true and bills nothing more.
The other routes do not page: their result has no next_cursor. Narrow the filters instead.
Understand the three result types
Lead-database rows carry name, first_name, last_name, headline, location, current_title, current_company, company_domain and linkedin_url. email is always empty there. The current job is the one on the person's own profile, self-reported and not verified: an employer filter matches what people say, which can include advisory or honorary roles.
The known-company route (apollo) returns the same fields plus email and email_status when Apollo holds a work email, and seniority. For known companies and a small result limit, this avoids a separate email lookup. detail: "short" on that route returns a masked preview with person_id values; person_ids then reveals the people you pick.
Preview, then reveal
When you want work emails for only some of the people at a company, look before you pay. The preview runs on the apollo route, costs the platform floor ($0.001485) and reveals nobody:
{
"capability": "people.search",
"input": {"company_domains": ["example.com"], "titles": ["VP Sales", "Head of Sales"], "detail": "short", "limit": 25},
"routing": {"provider": "apollo", "max_cost": "0.10"}
}
Each row carries a person_id, the first name, a masked last name (last_name_masked), current_title, current_company and has_email. Reveal only the people you pick, at the per-person price, up to 25 a call:
{
"capability": "people.search",
"input": {"person_ids": ["...", "..."]},
"routing": {"provider": "apollo", "max_cost": "0.10"}
}
The preview needs a domain, or at most 3 company names, and a limit of 25 or less. Pinning the provider keeps a preview that misses from falling through to another route.
On the LinkedIn route, RouterGrowth resolves the employer before searching. When a domain is supplied, the company website must match it. Returned people must have a current position carrying the resolved employer's ID or LinkedIn URL. A matching company name by itself is insufficient.
LinkedIn results include:
current_company,current_titleandcompany_linkedin_url: the position matching the requested employer, even when the person also has another job or board seat.current_positions: every explicitly current position on the profile, the matched one included, each withcompany,title,company_linkedin_urlandcompany_id.quality_flags: reviewretirement_mentionedandmissing_current_titlebefore using a row for outreach.quality.raw_profiles,quality.excluded_profilesandquality.employer_identity_checked: how many profiles were examined and excluded, and whether employer identity was checked. These fields are inside the run'sresult.
These fields are route-specific; do not require them on the two database routes' responses. An unconstrained LinkedIn search has employer_identity_checked: false because no employer was requested. Experience and skills are not in the normalized rows; response.include_raw adds the provider's own payload as result.raw when it fits in 256 kB.
Employer matching checks the provider's profile evidence. It does not independently verify a person's employment or prove that they are a qualified buyer. Review the role and flags. Identical profile URLs are deduplicated, but two accounts with the same person's name may still need manual review.
Get emails only after reviewing the people
The lead database and the LinkedIn route do not return emails. For a selected profile whose email is empty, pass its actual first_name, last_name and the matching employer's domain to contact.find. Do not invent a surname from initials. Before any send, run contact.verify on every address whose status is not valid; an email the apollo route already supplied needs no new lookup, only that check when its email_status is not valid.
A finished search carries next_steps with these calls filled in from its rows: a contact.find batch for the people without an email (a company.search for the employer's domain when the rows carry none), a contact.verify batch for the emails not marked valid, and the next page when there is one.
Report company candidates, qualified companies, matched people, found emails and verified emails separately. A successful people search does not mean every row has an email, or that any returned email has been verified.
When a search returns no match
- Check the domain for typos and confirm it belongs to the intended employer.
- Supply the exact LinkedIn company URL in
companies, paired with its domain when known. This avoids relying on a name lookup. - Check
hints, routing settings and the budget: remove an unintended provider pin, and permit another route only within your spending limit. - Broaden title variants or remove an unnecessary location restriction, while keeping the employer constraint.
- If you know a particular person's LinkedIn URL, use
person.enrichto inspect their role history. A name alone is not enough evidence to change the employer.
A lead-database search that finds nobody returns no_match and is not charged. An unresolved employer or a search where every profile lacks acceptable employer evidence returns no_match on the LinkedIn route and releases that attempt's hold. Automatic routing may try another eligible route. A final no-match does not mean the company has no employees; it may mean there is insufficient data to identify them reliably. Do not repeat the same query unchanged: the same input and routing that every route missed in the last 12 hours returns the earlier miss without calling any provider, free, unless you set routing.fresh: true.
Budget for the route and the result limit
The lead database quotes $0.001485 a call plus $0.000277 a person at the requested limit (25 people quote $0.008431, 200 quote $0.057051) and settles on the people actually returned. An empty search is not charged.
The LinkedIn route quotes $0.13 per search page of up to 25 profiles plus $0.0052 per requested full profile (nothing per profile with detail: "short", which returns truncated names and no titles). A company-constrained search adds an employer lookup of $0.026064 per employer to the quote. Examples for one employer:
| Requested full profiles | Catalog quote |
|---|---|
| 5 | $0.182064 |
| 25 | $0.286064 |
The quote includes the employer lookup even when you provide a LinkedIn company URL. The requested-limit quote remains the billing floor for a successful LinkedIn search: filtering out unsuitable profiles does not proportionally reduce its charge. Empty or unresolved attempts are not charged.
The apollo route charges $0.0312 per person actually returned, and a masked preview the platform floor. Take max_cost from inspect: waterfall.max_cost_for_all covers a call at the default limit (25) on every route, so a smaller limit needs less and a larger one more. Keep max_cost on every request, and read the run's billing.charged. See the people.search catalog entry for the current contract.
Reading this as an agent? This page as markdown: /docs/people-search.md · every page: /docs/llms.txt