> ## Documentation Index
> Fetch the complete documentation index at: https://www.forager.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Forager is a REST API for B2B people, company and job post data: contact lookups (phone numbers, personal emails, work emails), person, company and job post search, and bulk data feeds.
> Server: https://api-v2.forager.ai. Send the API key in the X-API-KEY header. Most paths include {account_id}. Read FORAGER_API_KEY and FORAGER_ACCOUNT_ID from the environment; never put the key in client-side code, logs or prompts.
> To add Forager to a project, follow https://www.forager.ai/docs/guides/agent-quickstart.md. To pick an endpoint, read https://www.forager.ai/docs/guides/choose-an-endpoint.md. For end-to-end builds, see https://www.forager.ai/docs/recipes/overview.md.
> Most requests spend credits. Do not guess costs; use https://www.forager.ai/docs/api-overview/credit-pricing.md and ask the user before spending credits.
> Use only endpoints and fields defined in https://www.forager.ai/docs/openapi.yaml. Forager has no MCP server for the API yet; the /mcp endpoint on this site searches the documentation only.
# People search API
> Search people by role, title, time period, organization, name, skills, industry and location.
## When to use this endpoint
You have criteria, not a person: a job title, a company, an industry, a location or skills, and want a page of matching people with their current role. Take `person.id` from a result into the contact lookups. Filters that take IDs come from the autocomplete endpoints.
## Example request
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/person_role_search/" \
-H "X-API-KEY: $FORAGER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"role_title": "Head of Data",
"role_is_current": true,
"organization_domains": [
"acme.com"
],
"page": 1
}'
```
Set `FORAGER_API_KEY` and `FORAGER_ACCOUNT_ID` as in the [quickstart](https://www.forager.ai/docs/api-overview/send-your-first-request.md).
## Example response
```json 200 (illustrative values) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"search_results": [
{
"id": 7001,
"role_title": "Head of Data",
"start_date": "2023-02-01",
"end_date": null,
"duration": "3 years",
"description": null,
"is_current": true,
"organization": {
"id": 90210,
"name": "Acme Example",
"legal_name": "Acme Example Inc.",
"website": "https://acme.com",
"domain": "acme.com",
"domain_rank": 48213,
"logo": null,
"description": "Example company used in the Forager docs.",
"founded_date": "2015-06-01",
"operating_status": "active",
"employees_range": "51-200",
"employees_amount": 120,
"keywords": [
{
"id": 311,
"name": "data infrastructure"
}
],
"location": {
"id": 10432,
"name": "Austin, Texas, United States",
"osm_locations": [
{
"id": 5,
"name": "Texas",
"place_type": "state"
}
]
},
"finance_info": {
"revenue": 25000000
},
"linkedin_info": {
"public_identifier": "acme-example",
"industry": {
"id": 4,
"name": "Software Development"
},
"public_profile_url": "https://www.linkedin.com/company/acme-example/"
},
"addresses": [
{
"street_number": "100",
"street_name": "Main St",
"city": "Austin",
"state": "TX",
"postcode": "78701",
"country": "United States",
"summary": "100 Main St, Austin, TX 78701, United States"
}
],
"date_updated": "2026-10-20T08:15:00Z",
"found_simple_events": [],
"found_funding_events": [],
"found_job_post_events": []
},
"person": {
"id": 48213,
"full_name": "Jane Doe",
"first_name": "Jane",
"last_name": "Doe",
"headline": "Head of Data at Acme Example",
"skills": [
{
"name": "SQL"
},
{
"name": "Data modeling"
}
],
"location": {
"id": 10432,
"name": "Austin, Texas, United States",
"osm_locations": [
{
"id": 5,
"name": "Texas",
"place_type": "state"
}
]
},
"linkedin_info": {
"public_identifier": "jane-doe-example",
"industry": {
"id": 4,
"name": "Software Development"
},
"public_profile_url": "https://www.linkedin.com/in/jane-doe-example/"
},
"date_updated": "2026-10-20T08:15:00Z"
},
"date_updated": "2026-10-20T08:15:00Z"
}
],
"total_search_results": 1
}
```
## Credits
Each request costs **1 credit**. See [API credits and pricing](https://www.forager.ai/docs/api-overview/credit-pricing.md) for how credits are charged and how to check what you spent.
## OpenAPI
````yaml POST /api/{account_id}/datastorage/person_role_search/
openapi: 3.0.3
info:
title: Forager public API
version: 1.0.0
description: Forager public API endpoints documentation
servers:
- url: https://api-v2.forager.ai
security: []
tags:
- name: Job Posts
description: >-
Search the Forager job-post index. Use these endpoints to find job
postings by attributes such as title, location, posted date, or hiring
organization, and to retrieve aggregate totals for a given query before
paginating through full results.
- name: Organizations
description: >-
Search the Forager organization index. Filter companies by attributes such
as industry, headcount, location, keywords, and web technologies, and
retrieve total match counts alongside the result set.
- name: People
description: >-
Look up people and their records. Use the search endpoints to find people
by role, employer, location, or skills, and the detail-lookup endpoints to
fetch a full person record by ID, email, or phone number. Contact data has
its own sections: Phones, Personal Emails, and Work Emails.
- name: Phones
description: >-
Retrieve phone numbers for a known person. Provide identifying information
(such as a LinkedIn handle or Forager ID) and get back the available phone
numbers.
- name: Personal Emails
description: >-
Retrieve personal email addresses for a known person. Returns addresses on
free webmail / consumer providers (Gmail, Outlook, Yahoo, iCloud, Proton,
and similar); corporate, educational, and other custom domains are
excluded to keep deliverability high.
- name: Work Emails
description: >-
Find and verify a person's work email address. Submit a lookup (single or
bulk), poll the job for its result, and optionally receive the result by
webhook when the job completes.
- name: Websites
description: >-
Look up information about a website, including the organization that owns
it and the technologies detected on the domain.
- name: Users
description: >-
Manage your Forager account. Retrieve the current authenticated user,
create and revoke API keys used to authenticate requests to the rest of
the API, and review the credit balance-change log that records every
lookup charge or adjustment against your account.
- name: Autocomplete
description: >-
Resolve free-text input into the canonical IDs used elsewhere in the API.
Each endpoint returns matching options for a search term (industries,
organizations, organization keywords, locations, person skills, web
technologies) so they can be passed as filters to the search endpoints.
- name: Feedback
description: >-
Report verification feedback for contact data (phone numbers, personal
emails, work emails) returned by Forager person lookups. Use these
endpoints to submit whether a contact value is valid/invalid and whether
it belongs to the matched person — every submission is stored as a new row
and is used to improve the accuracy of future lookups.
paths:
/api/{account_id}/datastorage/person_role_search/:
post:
tags:
- People
summary: Person role search
description: >-
The Person Role Search endpoint lets you search for individuals based on
their roles, titles, time periods, and associated organizations. You can
filter by attributes like role title or description, current status,
start/end dates, person name, skills, industry, and location. The
response returns matching person records along with their role history
and linked organization details (e.g. name, domain, founding date).
operationId: datastorage_person_role_search_create
parameters:
- in: path
name: account_id
schema:
type: integer
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationPersonRoleSearch'
examples:
Current Software Engineers:
value:
role_title: Software Engineer
role_is_current: true
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/OrganizationPersonRoleSearch'
multipart/form-data:
schema:
$ref: '#/components/schemas/OrganizationPersonRoleSearch'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRoleSearchResponse'
description: ''
'403':
$ref: '#/components/responses/AuthenticationFailed'
security:
- Api-Key: []
components:
schemas:
OrganizationPersonRoleSearch:
type: object
description: OrganizationPersonRole search request serializer.
properties:
page:
type: integer
role_title:
type: string
description: This field supports a boolean text search query.
role_description:
type: string
description: This field supports a boolean text search query.
role_is_current:
type: boolean
default: true
role_position_start_date:
type: string
format: date
role_position_end_date:
type: string
format: date
role_years_on_position_start:
type: integer
role_years_on_position_end:
type: integer
person_name:
type: string
description: This field supports a boolean text search query.
person_headline:
type: string
description: This field supports a boolean text search query.
person_description:
type: string
description: This field supports a boolean text search query.
person_skills:
type: array
items:
type: integer
description: >-
To get a list of IDs use Person skills
lookup endpoint.
person_locations:
type: array
items:
type: integer
description: >-
To get a list of IDs use Locations lookup
endpoint.
person_industries:
type: array
items:
type: integer
description: >-
To get a list of IDs use Industries lookup
endpoint.
person_industries_exclude:
type: array
items:
type: integer
description: >-
To get a list of IDs use Industries lookup
endpoint.
person_linkedin_public_identifiers:
type: array
items:
type: string
description: >-
LinkedIn person "Public identifier/Slug/ID" -
"linkedin.com/in/!slug!/".
organizations:
type: array
items:
type: integer
description: >-
To get a list of IDs use Organizations
lookup endpoint.
organizations_bulk_domain:
type: string
organization_domains:
type: array
items:
type: string
description: This field supports a boolean text search query.
organization_description:
type: string
description: This field supports a boolean text search query.
organization_locations:
type: array
items:
type: integer
description: >-
To get a list of IDs use Locations lookup
endpoint.
organization_industries:
type: array
items:
type: integer
description: >-
To get a list of IDs use Industries lookup
endpoint.
organization_industries_exclude:
type: array
items:
type: integer
description: >-
To get a list of IDs use Industries lookup
endpoint.
organization_keywords:
type: array
items:
type: integer
description: >-
To get a list of IDs use Organization
keywords lookup endpoint.
organization_web_technologies:
type: array
items:
type: integer
description: >-
To get a list of IDs use Web
technologies lookup endpoint.
organization_founded_date_start:
type: string
format: date
organization_founded_date_end:
type: string
format: date
organization_employees_start:
type: integer
organization_employees_end:
type: integer
organization_revenue_start:
type: integer
organization_revenue_end:
type: integer
organization_domain_rank_start:
type: integer
organization_domain_rank_end:
type: integer
organization_linkedin_public_identifiers:
type: array
items:
type: string
description: >-
LinkedIn organization "Public identifier/Slug/ID" -
"linkedin.com/company/!slug!/".
funding_types:
type: array
items:
$ref: '#/components/schemas/FundingTypesEnum'
funding_total_start:
type: integer
funding_total_end:
type: integer
funding_event_date_featured_start:
type: string
format: date
funding_event_date_featured_end:
type: string
format: date
job_post_title:
type: string
description: This field supports a boolean text search query.
job_post_description:
type: string
description: This field supports a boolean text search query.
job_post_is_remote:
type: boolean
nullable: true
job_post_is_active:
type: boolean
nullable: true
job_post_date_featured_start:
type: string
format: date
job_post_date_featured_end:
type: string
format: date
job_post_locations:
type: array
items:
type: integer
description: >-
To get a list of IDs use Locations lookup
endpoint.
job_post_locations_exclude:
type: array
items:
type: integer
description: >-
To get a list of IDs use Locations lookup
endpoint.
simple_event_source:
$ref: '#/components/schemas/SimpleEventSourceEnum'
simple_event_reason:
$ref: '#/components/schemas/SimpleEventReasonEnum'
simple_event_date_featured_start:
type: string
format: date
simple_event_date_featured_end:
type: string
format: date
PersonRoleSearchResponse:
type: object
description: OrganizationPersonRole search response serializer.
properties:
search_results:
type: array
items:
$ref: '#/components/schemas/OrganizationPersonRoleSearchResult'
readOnly: true
total_search_results:
type: integer
minimum: 0
required:
- search_results
- total_search_results
FundingTypesEnum:
enum:
- angel
- convertible_note
- corporate_round
- debt_financing
- equity_crowdfunding
- grant
- initial_coin_offering
- non_equity_assistance
- post_ipo_debt
- post_ipo_equity
- post_ipo_secondary
- pre_seed
- private_equity
- product_crowdfunding
- secondary_market
- seed
- series_a
- series_b
- series_c
- series_d
- series_e
- series_f
- series_g
- series_h
- series_i
- series_j
- series_unknown
- undisclosed
type: string
description: |-
* `angel` - Angel
* `convertible_note` - Convertible Note
* `corporate_round` - Corporate Round
* `debt_financing` - Debt Financing
* `equity_crowdfunding` - Equity Crowdfunding
* `grant` - Grant
* `initial_coin_offering` - Initial coin offering (ICO)
* `non_equity_assistance` - Non-Equity Assistance
* `post_ipo_debt` - Post-IPO Debt
* `post_ipo_equity` - Post-IPO Equity
* `post_ipo_secondary` - Post-IPO Secondary
* `pre_seed` - Pre-Seed
* `private_equity` - Private Equity
* `product_crowdfunding` - Product Crowdfunding
* `secondary_market` - Secondary Market
* `seed` - Seed
* `series_a` - Series A
* `series_b` - Series B
* `series_c` - Series C
* `series_d` - Series D
* `series_e` - Series E
* `series_f` - Series F
* `series_g` - Series G
* `series_h` - Series H
* `series_i` - Series I
* `series_j` - Series J
* `series_unknown` - Venture - Series Unknown
* `undisclosed` - Undisclosed
SimpleEventSourceEnum:
enum:
- product_hunt
- form_c_sec_gov
- form_d_sec_gov
type: string
description: |-
* `product_hunt` - Product Hunt
* `form_c_sec_gov` - Form C sec.gov
* `form_d_sec_gov` - Form D sec.gov
SimpleEventReasonEnum:
enum:
- report_released
- promoted_on_site
type: string
description: |-
* `report_released` - Report released
* `promoted_on_site` - Promoted on site
OrganizationPersonRoleSearchResult:
type: object
description: Serializer for OrganizationPersonRole search results.
properties:
id:
type: integer
readOnly: true
role_title:
type: string
nullable: true
maxLength: 255
start_date:
type: string
format: date
nullable: true
end_date:
type: string
format: date
nullable: true
duration:
type: string
nullable: true
title: Role duration
maxLength: 255
description:
type: string
nullable: true
is_current:
type: boolean
title: Is current?
organization:
allOf:
- $ref: '#/components/schemas/OrganizationSearchResult'
readOnly: true
person:
allOf:
- $ref: '#/components/schemas/PersonChild'
readOnly: true
date_updated:
type: string
format: date-time
readOnly: true
required:
- date_updated
- id
- is_current
- organization
- person
OrganizationSearchResult:
type: object
description: Organization search result(With prefetch events) serializer.
properties:
id:
type: integer
readOnly: true
name:
type: string
maxLength: 255
legal_name:
type: string
maxLength: 255
website:
type: string
format: uri
nullable: true
maxLength: 16384
domain:
type: string
format: uri
nullable: true
maxLength: 200
domain_rank:
type: integer
nullable: true
description: Domain rank.
readOnly: true
logo:
type: string
format: uri
nullable: true
maxLength: 510
description:
type: string
nullable: true
founded_date:
type: string
format: date
nullable: true
operating_status:
type: string
nullable: true
maxLength: 255
employees_range:
type: string
nullable: true
maxLength: 255
employees_amount:
type: integer
maximum: 2147483647
minimum: 0
nullable: true
keywords:
type: array
items:
$ref: '#/components/schemas/OrganizationKeyword'
readOnly: true
location:
allOf:
- $ref: '#/components/schemas/InnerLocation'
readOnly: true
finance_info:
allOf:
- $ref: '#/components/schemas/OrganizationFinanceInfo'
readOnly: true
linkedin_info:
allOf:
- $ref: '#/components/schemas/OrganizationLinkedinInfo'
readOnly: true
addresses:
type: array
items:
$ref: '#/components/schemas/OrganizationAddress'
readOnly: true
date_updated:
type: string
format: date-time
readOnly: true
found_simple_events:
type: array
items:
$ref: '#/components/schemas/OrganizationSimpleEvent'
description: >-
Events will be available in case any event field would be used for
the search. In results will be available 30 most recent matches.
found_funding_events:
type: array
items:
$ref: '#/components/schemas/OrganizationFundingEvent'
description: >-
Events will be available in case any event field would be used for
the search. In results will be available 30 most recent matches.
found_job_post_events:
type: array
items:
$ref: '#/components/schemas/OrganizationJobPostEvent'
description: >-
Events will be available in case any event field would be used for
the search. In results will be available 30 most recent matches.
required:
- addresses
- date_updated
- domain_rank
- finance_info
- found_funding_events
- found_job_post_events
- found_simple_events
- id
- keywords
- legal_name
- linkedin_info
- location
- name
PersonChild:
type: object
description: Child serializer for the Person model.
properties:
id:
type: integer
readOnly: true
full_name:
type: string
maxLength: 255
first_name:
type: string
maxLength: 255
last_name:
type: string
nullable: true
maxLength: 255
photo:
type: string
format: uri
nullable: true
maxLength: 255
gender:
type: string
nullable: true
maxLength: 255
headline:
type: string
nullable: true
maxLength: 255
description:
type: string
nullable: true
skills:
type: array
items:
$ref: '#/components/schemas/PersonSkill'
readOnly: true
location:
allOf:
- $ref: '#/components/schemas/InnerLocation'
readOnly: true
linkedin_info:
allOf:
- $ref: '#/components/schemas/PersonLinkedinInfo'
readOnly: true
date_updated:
type: string
format: date-time
readOnly: true
required:
- date_updated
- first_name
- full_name
- id
- linkedin_info
- location
- skills
OrganizationKeyword:
type: object
description: Serializer for the OrganizationKeyword model.
properties:
id:
type: integer
readOnly: true
name:
type: string
maxLength: 255
required:
- id
- name
InnerLocation:
type: object
description: Serializer for the InnerLocation model.
properties:
id:
type: integer
readOnly: true
name:
type: string
maxLength: 255
osm_locations:
type: array
items:
$ref: '#/components/schemas/OSMLocation'
readOnly: true
required:
- id
- name
- osm_locations
OrganizationFinanceInfo:
type: object
description: Serializer for the OrganizationFinanceInfo model.
properties:
revenue:
type: integer
maximum: 9223372036854776000
minimum: 0
format: int64
nullable: true
OrganizationLinkedinInfo:
type: object
description: Serializer for the OrganizationLinkedinInfo model.
properties:
public_identifier:
type: string
nullable: true
maxLength: 255
industry:
allOf:
- $ref: '#/components/schemas/LinkedinIndustry'
readOnly: true
public_profile_url:
type: string
nullable: true
description: Get LinkedIn public profile URL.
readOnly: true
required:
- industry
- public_profile_url
OrganizationAddress:
type: object
description: Serializer for the OrganizationAddress model.
properties:
street_number:
type: string
nullable: true
maxLength: 255
street_name:
type: string
nullable: true
maxLength: 255
city:
type: string
nullable: true
maxLength: 255
state:
type: string
nullable: true
title: State/County
maxLength: 255
postcode:
type: string
nullable: true
title: Post/Zip-code
maxLength: 64
country:
type: string
maxLength: 255
summary:
type: string
required:
- country
- summary
OrganizationSimpleEvent:
type: object
description: Serializer for the OrganizationSimpleEvent model.
properties:
id:
type: integer
readOnly: true
source:
allOf:
- $ref: '#/components/schemas/SourceA7bEnum'
readOnly: true
date_featured:
type: string
format: date
organization_id:
type: integer
readOnly: true
reason:
$ref: '#/components/schemas/ReasonEnum'
url:
type: string
format: uri
maxLength: 255
required:
- date_featured
- id
- organization_id
- reason
- source
- url
OrganizationFundingEvent:
type: object
description: Serializer for the OrganizationFundingEvent model.
properties:
id:
type: integer
readOnly: true
source:
allOf:
- $ref: '#/components/schemas/OrganizationFundingEventSourceEnum'
readOnly: true
date_featured:
type: string
format: date
organization_id:
type: integer
readOnly: true
funding_type:
type: string
maxLength: 255
funding_total:
type: integer
maximum: 9223372036854776000
minimum: 0
format: int64
required:
- date_featured
- funding_total
- funding_type
- id
- organization_id
- source
OrganizationJobPostEvent:
type: object
description: Serializer for the OrganizationJobPostEvent model.
properties:
id:
type: integer
readOnly: true
source:
allOf:
- $ref: '#/components/schemas/Source089Enum'
readOnly: true
date_featured:
type: string
format: date
organization_id:
type: integer
readOnly: true
source_id:
type: string
maxLength: 65
url:
type: string
format: uri
maxLength: 510
title:
type: string
maxLength: 255
is_remote:
type: boolean
title: Is remote?
is_active:
type: boolean
title: Is active?
required:
- date_featured
- id
- is_active
- is_remote
- organization_id
- source
- source_id
- title
- url
PersonSkill:
type: object
description: Serializer for the PersonSkill model.
properties:
name:
type: string
maxLength: 255
required:
- name
PersonLinkedinInfo:
type: object
description: Serializer for the PersonLinkedinInfo model.
properties:
public_identifier:
type: string
nullable: true
maxLength: 255
industry:
allOf:
- $ref: '#/components/schemas/LinkedinIndustry'
readOnly: true
public_profile_url:
type: string
description: Get LinkedIn public profile URL.
readOnly: true
required:
- industry
- public_profile_url
OSMLocation:
type: object
description: Serializer for the OSMLocation model.
properties:
id:
type: integer
readOnly: true
name:
type: string
maxLength: 255
place_type:
type: string
title: Type
maxLength: 255
required:
- id
- name
- place_type
LinkedinIndustry:
type: object
description: Serializer for the LinkedinIndustry document.
properties:
id:
type: integer
readOnly: true
name:
type: string
maxLength: 255
required:
- id
- name
SourceA7bEnum:
enum:
- product_hunt
- form_c_sec_gov
- form_d_sec_gov
type: string
description: |-
* `product_hunt` - Product Hunt
* `form_c_sec_gov` - Form C sec.gov
* `form_d_sec_gov` - Form D sec.gov
ReasonEnum:
enum:
- report_released
- promoted_on_site
type: string
description: |-
* `report_released` - Report released
* `promoted_on_site` - Promoted on site
OrganizationFundingEventSourceEnum:
enum:
- crunchbase
type: string
description: '* `crunchbase` - Crunchbase'
Source089Enum:
enum:
- indeed
- linkedin
- angellist
type: string
description: |-
* `indeed` - Indeed
* `linkedin` - LinkedIn
* `angellist` - AngelList
responses:
AuthenticationFailed:
description: >-
The X-API-KEY header is missing, the key is not valid, or the key does
not have permission for this resource.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example:
detail: Authentication credentials were not provided.
securitySchemes:
Api-Key:
type: apiKey
in: header
name: X-API-KEY
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.