Offer people search as an agent tool

Let an agent find the people who hold a role at a target company and read their profiles, as a search tool with typed filters rather than a browsing session.

Get a free API key + $5 Get a sample run

Free API key
No credit card
Run your sample

A selection of teams that run this job on Forager · plus other teams on Forager

Uses POST /person_role_search/, POST /person_detail_lookup/ · People search API reference

What it costs: Charged per request: credit pricing.

How the data flows

3 inputs → People search + Person enrichment → 5 fields sample data

01 · Inputs

Company domain

example.com

Title

VP Revenue Operations

location

linkedin.com/in/priya-fixture

02 · Forager

People search + Person enrichment POST /person_role_search/

Match found

03 · Outputs

Priya FixtureVP Revenue Operations · Example Inc.

person id: per_8f3a1c
title: VP Revenue Operations
employer: Example Inc.
profile fields: /in/priya-fixture
name: Priya Fixture
mobile: +44 20 7946 0958

5 fields in the responseexample data

Steps

Expose a find_people tool that maps the agent's request to POST /person_role_search/ filters: title, seniority, department, location and company
Check the _totals endpoint first so the tool can report how many matches exist before it pages
Return each match as a typed record with person_id, name, title and employer
Let the agent call POST /person_detail_lookup/ for the one or two people it chooses, not the whole result set

import json, os, requests

BASE = "https://api-v2.forager.ai/api/{account_id}/datastorage"
HEADERS = {"X-API-KEY": os.environ["FORAGER_KEY"]}
body = json.load(open("request.json"))  # request fields: see the API reference

# 1. Expose a find_people tool that maps the agent's request to POST
# /person_role_search/ filters: title, seniority, department, location and
# company
r1 = requests.post(f"{BASE}/person_role_search/", headers=HEADERS, json=body)

# 2. Check the _totals endpoint first so the tool can report how many
# matches exist before it pages

# 3. Return each match as a typed record with person_id, name, title and
# employer

# 4. Let the agent call POST /person_detail_lookup/ for the one or two
# people it chooses, not the whole result set
r2 = requests.post(f"{BASE}/person_detail_lookup/", headers=HEADERS, json=body)

# 1. POST /person_role_search/
curl -X POST \
  https://api-v2.forager.ai/api/{account_id}/datastorage/person_role_search/ \
  -H "X-API-KEY: $FORAGER_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

# 2. POST /person_detail_lookup/
curl -X POST \
  https://api-v2.forager.ai/api/{account_id}/datastorage/person_detail_lookup/ \
  -H "X-API-KEY: $FORAGER_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Generated from the recipe stepsRequest fields: API reference

Run it yourself: People search API reference

Get a free API key + $5 Get a sample run

Free API key
No credit card
Run your sample

Inputs and outputs

Inputs	Outputs
company domain or name	`person_id`
title or seniority filters	`full name`
location	`title`
	`employer`
	`profile fields`

Questions about this recipe

How can my agent search for people by role at a company?

Expose a find_people tool that maps the agent's request to POST /person_role_search/ filters: title, seniority, department, location and company. Let the agent call POST /person_detail_lookup/ for the one or two people it chooses, not the whole result set.

What does it cost to offer people search as an agent tool?

People search: people search 1 credit per request and people search: role details 1 credit per request, charged whether or not data comes back. Person enrichment: 1 credit per request, charged whether or not data comes back. Growth's 8,250 monthly credits cover 8,250 search requests, or a mix. Self-serve plans are Starter, Growth, Pro and Scale. See plans and prices

What do I need to run this recipe, and what comes back?

You send company domain or name, location and title or seniority filters. You get back employer, full name, person_id and profile fields, as JSON. You also need a Forager API key, which comes with a free account.

Which people search API returns typed results an agent can use?

This recipe uses Forager People search and Person enrichment. People search: Find the people who hold a role at target companies, filtered by title, seniority, department and location. Let an agent find the people who hold a role at a target company and read their profiles, as a search tool with typed filters rather than a browsing session.

Is there a free way to try Forager on this workflow?

Yes. Create a free account at app.forager.ai: it comes with $5 in free credits and an API key, and there is no credit card to sign up. Run it on records you already know, or book a demo and send us a list: we run it and show you what we find.

When should I run this workflow?

An agent is asked to find the head of security at a list of companies and start a conversation with each. The agent finds the right person in one tool call, and the platform pays for the profiles it opens rather than for the search.

Which Forager products does this recipe use?

People search and person enrichment. People search: find the people who hold a role at target companies, filtered by title, seniority, department and location. Person enrichment: a full professional profile for a person from a LinkedIn URL, email or phone: experience, education, skills and contact channels.

How do I know the data is right?

The test that counts is your own: send a list of profiles you care about. We run it and show you what we find, number by number, so you can measure hit rate and connect rate yourself.

How do I find decision makers tool for agent?

Expose a find_people tool that maps the agent's request to POST /person_role_search/ filters: title, seniority, department, location and company. Check the _totals endpoint first so the tool can report how many matches exist before it pages.

Which tools can run this workflow?

Native in Clay, partner-built in Deepline and Cargo and called through the API from your own code, Make and n8n. Or call the endpoints in the steps above from your own code with one API key.

How many steps is this workflow?

4 steps: expose a find_people tool that maps the agent's request to POST /person_role_search/ filters: title, seniority, department, location and company, check the _totals endpoint first so the tool can report how many matches exist before it pages, return each match as a typed record with person_id, name, title and employer and let the agent call POST /person_detail_lookup/ for the one or two people it chooses, not the whole result set.

Is there a contract or minimum commitment?

No contract to start: a free account comes with $5 in credits. To keep using Forager, choose a monthly or yearly plan. Monthly plans cancel anytime and unused credits roll over; yearly plans grant all credits upfront and cost 10% less. Larger volumes are agreed with our team.

A selection of teams that run this job on Forager · plus other teams on Forager

Clay
- GTM workflow builders
Selected use case: Forager mobile numbers, emails and people data inside Clay tables.
Juicebox
- AI candidate sourcing
Selected use case: Forager data behind its PeopleGPT search and sourcing agents.
Nooks
- Power & parallel dialers
Selected use case: mobile numbers inside their dialer.
Emergent Labs
- Agent builders
AI app-building platform where agents design, code and deploy full-stack apps.
Deepline
- Waterfall enrichment
Selected use case: Forager lookups as typed tools inside enrichment waterfalls.

19 typed Forager tools available inside Deepline¹
HubSpot
- CRM add-ons
Selected use case: enriching contact and company records with people, company and job-posting data.
BetterContact
- Waterfall enrichment
Selected use case: a Forager step in its waterfall for mobile numbers.
Salto
- Internal use
Platform for governed configuration changes across business systems.

Sources

¹ Deepline: deepline.com/integrations/forager (public page, read 2026-10-21).

Offer people search as an agent tool

How the data flows

Steps

Inputs and outputs

Questions about this recipe

How can my agent search for people by role at a company?

What does it cost to offer people search as an agent tool?

What do I need to run this recipe, and what comes back?

Which people search API returns typed results an agent can use?

Is there a free way to try Forager on this workflow?

When should I run this workflow?

Which Forager products does this recipe use?

How do I know the data is right?

How do I find decision makers tool for agent?

Which tools can run this workflow?

How many steps is this workflow?

Is there a contract or minimum commitment?

More recipes for agent builders

Give coding agents typed people and company data tools

Offer people and company data as a built-in integration in an AI app builder

Add Forager as a waterfall step in an agent's contact tool

Ground an agent's account research with company enrichment

Detect CRM contacts who changed jobs and alert on moved champions

Back a sales-intelligence database with an additional mobile source

Put people, company and job data your users can act on inside your product