Skip to main content
Recipe prompt
Build a prospect list: role, company and location filters produce a list of peopleBuild a prospect list: role, company and location filters produce a list of people

What you’ll build

A list builder with a review step. You describe the people you want by title and company industry. Forager returns matching people with their current role and company. You keep the ones you want and spend credits on contact data only for those.

Steps

1

Resolve filter names to IDs

Search filters take IDs, not names. Call Industries lookup with q. The response has results, each with an id and text.
The id comes back as a string and the search expects integers, so convert it. Let the user pick the right match instead of taking the first. Other filters work the same way; see Find filter values.
2

Search people by role

Send a POST to Person role search. role_title supports a boolean text query.
Each hit has person (with id, full_name and linkedin_info), role_title, and organization (with name and domain). total_search_results is the match count. Narrow by company with organization_employees_start and organization_employees_end, organization_locations, or organization_domains. To count matches first, use Person role search totals, which takes the same body.
3

Look up contacts for the people you keep

After review, call Phone numbers lookup once per kept person. Use Personal emails lookup the same way, or the bulk work email lookup.

Handle the edge cases

  • Not found. If search_results is empty, tell the user and suggest loosening a filter. A person with no phone numbers returns an empty list.
  • 403. The key is missing or invalid. Fix the credentials; do not retry.
  • 429. Autocomplete allows 10 requests per second per account, so cache IDs. Back off on any 429. See errors and rate limits.
  • Paging. Request further pages with page until you have the number of hits in total_search_results.
  • Credits. A role search costs 1 credit per request and a phone number lookup 15 credits per lookup. Autocomplete is free. See credit pricing.

Search people by role

Every role search filter.

Find filter values

Which autocomplete feeds which filter.

Search organizations

Start from companies instead of titles.
Last modified on October 28, 2026