> ## 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.

# Choose the right endpoint

> Pick the right Forager API endpoint for what you already know and what you need back, with the credit cost of each call.

![Choose the right Forager API endpoint: inputs such as a profile URL, email, phone or filters map to the endpoint that returns what you need](https://mintcdn.com/forager/EGsWCxLOYv1Cb__c/images/illustrations/choose-endpoint-input-to-output-map.svg?fit=max\&auto=format\&n=EGsWCxLOYv1Cb__c\&q=85\&s=9221cecaaec35f71e800869ee51e69d7)

Start from what you already have, then follow the row to the endpoint that returns what you need. Searching and counting first, then looking up contact details only for the people you keep, is usually the cheapest path.

## You have a person

| You have | You need | Endpoint | Credits |
| - | - | - | - |
| LinkedIn handle or Forager person ID | Full profile (roles, education, skills, location) | [Person lookup API](https://www.forager.ai/docs/openapi/people/datastorage_person_detail_lookup_create.md) | 1 |
| LinkedIn handle or Forager person ID | Phone numbers | [Phone number lookup API](https://www.forager.ai/docs/openapi/phones/datastorage_person_contacts_lookup_phone_numbers_create.md) | 15 |
| LinkedIn handle or Forager person ID | Personal emails | [Personal email lookup API](https://www.forager.ai/docs/openapi/personal-emails/datastorage_person_contacts_lookup_personal_emails_create.md) | 5, only when at least one address is returned |
| Name and company domain, or LinkedIn handle | Work email | [Work email finder API](https://www.forager.ai/docs/openapi/work-emails/v2_datastorage_person_contacts_lookup_work_emails_create.md) | 5, only when an address is found |
| Many people at once | Work emails | [Bulk work email finder API](https://www.forager.ai/docs/openapi/work-emails/v2_datastorage_person_contacts_lookup_work_emails_bulk_create.md) | 5 per lookup, only when an address is found |
| A personal email address | The person behind it | [Reverse email lookup API](https://www.forager.ai/docs/openapi/people/datastorage_person_detail_reverse_lookup_by_email_create.md) | 5 |
| A phone number | The person behind it | [Reverse phone lookup API](https://www.forager.ai/docs/openapi/people/datastorage_person_detail_reverse_lookup_by_phone_number_create.md) | 15 |

## You have criteria, not a person

![Search first, keep the people you need, then run contact lookups to save Forager API credits](https://mintcdn.com/forager/OnhSHNo_LBQ7yKjR/images/illustrations/search-then-lookup-credit-flow.svg?fit=max\&auto=format\&n=OnhSHNo_LBQ7yKjR\&q=85\&s=71e8c4178e9fa1e1db32978d5a043926)

| You want | Endpoint | Credits |
| - | - | - |
| People by job title, company, industry, location or skills | [People search API](https://www.forager.ai/docs/openapi/people/datastorage_person_role_search_create.md) | 1 per call |
| Companies by industry, size, revenue, funding, location or technology | [Company search API](https://www.forager.ai/docs/openapi/organizations/datastorage_organization_search_create.md) | 1 per call |
| Job postings by title, company, location or date | [Job postings API](https://www.forager.ai/docs/openapi/job-posts/datastorage_job_search_create.md) | 2 per call |
| A website's traffic ranks, traffic estimate and web technologies, from its domain | [Website lookup API](https://www.forager.ai/docs/openapi/websites/datastorage_website_detail_lookup_create.md) | 1 |
| How many people a search would return | [People search totals API](https://www.forager.ai/docs/openapi/people/datastorage_person_role_search_totals_create.md) | 1 |
| How many companies or job postings a search would return | The `totals` endpoint next to the company or job search | Not yet documented |

Search filters such as industries, locations, skills, keywords and technologies take IDs, not free text. Get the IDs from the [autocomplete endpoints](https://www.forager.ai/docs/guides/find-filter-values.md) first.

## Typical flows

**1. Build a prospect list**

Resolve filter IDs with autocomplete, run [People search](https://www.forager.ai/docs/openapi/people/datastorage_person_role_search_create.md), then look up a [work email](https://www.forager.ai/docs/openapi/work-emails/v2_datastorage_person_contacts_lookup_work_emails_create.md) or [phone number](https://www.forager.ai/docs/openapi/phones/datastorage_person_contacts_lookup_phone_numbers_create.md) only for the people you keep. Guide: [Search people by role](https://www.forager.ai/docs/guides/search-people-by-role.md).

**2. Enrich a CRM contact**

Start from the LinkedIn handle with [Person lookup](https://www.forager.ai/docs/openapi/people/datastorage_person_detail_lookup_create.md), or from an email with [Reverse email lookup](https://www.forager.ai/docs/openapi/people/datastorage_person_detail_reverse_lookup_by_email_create.md). Guide: [Enrich a contact](https://www.forager.ai/docs/guides/enrich-a-contact.md).

**3. Enrich thousands of contacts**

Use the [bulk work email finder](https://www.forager.ai/docs/openapi/work-emails/v2_datastorage_person_contacts_lookup_work_emails_bulk_create.md) with a `webhook_url` instead of polling. Guide: [Bulk work emails](https://www.forager.ai/docs/guides/bulk-work-emails.md). For whole datasets, a [data feed](https://www.forager.ai/docs/data-license/v2/data-feed-overview.md) is usually cheaper than the API.

Costs come from [API credits and pricing](https://www.forager.ai/docs/api-overview/credit-pricing.md), which is the source of truth if the two ever differ.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.