---
name: forager-api
description: Call the Forager B2B data API to look up people, phone numbers, personal and work emails, organizations, job posts and websites. Use when the user wants to enrich a contact, find contact details, search people or companies, or check Forager credit usage. Requires a Forager API key and Account ID.
license: Proprietary. Use is subject to Forager's terms.
compatibility: Needs network access to https://api-v2.forager.ai and a Forager API key supplied by the user (never ask for it in chat logs or write it to files).
metadata:
  source: https://www.forager.ai/docs
  openapi: https://www.forager.ai/docs/openapi.yaml
---

# Forager API

Forager provides people, company and job-post data through a REST API. Most requests cost credits, so plan calls before you make them.

## When to use this skill

- Find a person by role or title, or fetch a person record.
- Get phone numbers, personal emails or work emails for a known person.
- Search organizations or job posts.
- Look up a website and the technologies detected on it.
- Check credit usage or manage API keys.

Do not use it for bulk flat-file data. That is the separate data feed product (annual license); point the user to https://www.forager.ai/docs/data-license/v2/data-feed-overview.

## Setup and authentication

- Base URL: `https://api-v2.forager.ai`
- Send the API key in the `X-API-KEY` header on every request.
- Most paths contain `{account_id}`, the user's integer Account ID (shown on https://app.forager.ai/profile). Ask the user for it if you do not have it.
- Keys are created at https://app.forager.ai/keys. Never print the key, put it in a URL or commit it. Read it from an environment variable or a secret store the user names.
- Full machine-readable spec: https://www.forager.ai/docs/openapi.yaml

## Pick the endpoint

- Have a LinkedIn handle or Forager person ID: person lookup (1 credit), then phone numbers (15) or personal emails (5, not charged when no address is returned) only if the user needs them.
- Have a name plus company domain: work email finder (5 credits, charged only when an address is found).
- Have only an email or a phone number: reverse email (5) or reverse phone (15) lookup.
- Have criteria, not a person: people, company or job search (1, 1, 2 per call), after resolving every ID filter with autocomplete.
- Need many work emails: the bulk endpoint with `webhook_url`, never a loop of single lookups.
- Need a whole dataset: recommend the data feed, not the API.

Full table: https://www.forager.ai/docs/guides/choose-an-endpoint

## Core tasks and endpoints

| Task | Method and path | Body fields (from the spec) |
| --- | --- | --- |
| Person record | `POST /api/{account_id}/datastorage/person_detail_lookup/` | `person_id` or `linkedin_public_identifier` |
| Person by email | `POST /api/{account_id}/datastorage/person_detail_reverse_lookup/by_email/` | `email` |
| Person by phone | `POST /api/{account_id}/datastorage/person_detail_reverse_lookup/by_phone_number/` | `phone_number` |
| Search people by role | `POST /api/{account_id}/datastorage/person_role_search/` | `role_title`, `role_is_current`, many person and organization filters, `page` |
| Count role-search matches | `POST /api/{account_id}/datastorage/person_role_search/totals/` | same as role search |
| Phone numbers | `POST /api/{account_id}/datastorage/person_contacts_lookup/phone_numbers/` | `person_id` or `linkedin_public_identifier` |
| Personal emails | `POST /api/{account_id}/datastorage/person_contacts_lookup/personal_emails/` | `person_id` or `linkedin_public_identifier` |
| Work email (one, async) | `POST /api/v2/{account_id}/datastorage/person_contacts_lookup/work_emails/` | `first_name`, `last_name`, `domain`, or `linkedin_public_identifier`; optional `webhook_url` |
| Work email result | `GET /api/v2/{account_id}/datastorage/person_contacts_lookup/work_emails/{job_id}/` | none |
| Work emails (bulk, async) | `POST /api/v2/{account_id}/datastorage/person_contacts_lookup/work_emails/bulk/` | `email_lookups` (list of single lookups); optional `webhook_url` |
| Bulk result | `GET /api/v2/{account_id}/datastorage/person_contacts_lookup/work_emails/bulk/{batch_id}/` | none |
| Search organizations | `POST /api/{account_id}/datastorage/organization_search/` | `domains`, `industries`, `locations`, `employees_start`, `employees_end`, ... , `page` |
| Count organization matches | `POST /api/{account_id}/datastorage/organization_search/totals/` | same as organization search |
| Search job posts | `POST /api/{account_id}/datastorage/job_search/` | `title`, `is_remote`, `is_active`, `locations`, ..., `page` |
| Website details | `POST /api/{account_id}/datastorage/website_detail_lookup/` | `domain`, `organization_id` or `organization_linkedin_public_identifier` |
| Credit log | `GET /api/{account_id}/subscriptions/balance_change_logs/` | none |
| Credit totals | `GET /api/{account_id}/subscriptions/balance_change_logs/totals/` | none |

Filters that take numeric IDs (industries, locations, person skills, organizations, organization keywords, web technologies) get their IDs from the autocomplete endpoints, for example `GET /api/{account_id}/datastorage/autocomplete/locations/?q=...`. Do not guess IDs.

Example request:

```bash
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": "Software Engineer", "role_is_current": true}'
```

The role search response has `search_results` and `total_search_results`. Take `person.id` from a result to use as `person_id` in the contact lookups.

## Credit-awareness rules

1. Before any call, check the cost in https://www.forager.ai/docs/api-overview/credit-pricing. Documented costs per lookup: person detail 1, person role search 1, role search totals 1, organization search 1, website lookup 1, job search 2, work email 5 (single and bulk, charged only when an address is found), personal email 5 (not charged when no address is returned), reverse email 5, phone number 15, reverse phone 15. Autocomplete, feedback and polling a work email job or batch are free. The cost of job search totals, organization search totals and the account, API key and credit usage endpoints: Not yet documented. Say so and do not guess.
2. Tell the user the number of calls and the credits they are expected to use before running more than a handful of requests, and ask for confirmation for large runs.
3. Never loop over results calling a paid endpoint without the user agreeing to the total.
4. For many work emails use the bulk endpoint, not repeated single lookups. A bulk batch is rejected, and nothing is charged, if the credit balance cannot cover it.
5. Polling a work email job or batch is free. Respect the `Retry-After` header when present. Work email credits are charged once, only when an address is found.
6. Autocomplete is limited to 10 requests per second per account (HTTP 429). Feedback endpoints are limited to 60 requests per minute per account (HTTP 429). On 429, wait and retry with backoff.
7. Check usage with the credit log and totals endpoints when asked.

## Errors

- A missing or invalid API key returns HTTP 403 with `{"detail": "Authentication credentials were not provided."}` (verified Oct 2026). Check the key and the Account ID, and do not retry in a loop.
- 400 on the feedback endpoints means a validation failure in the body.
- Other error behaviour is not documented. Report the status code and body to the user instead of guessing.

## Before you report success

- Every ID filter came from an autocomplete call, not a guess.
- The user approved the credit total for anything beyond a handful of calls.
- You read `total_search_results` before paging through a search.
- Async work email jobs reached a final state (or the webhook fired) before you report results.
- You did not print, log or commit the API key.

## Feedback on data quality

If the user learns whether a phone number is connected or an email is valid, offer to send feedback with the `feedback/phone_numbers`, `feedback/personal_emails` or `feedback/work_emails` endpoints (all under `/api/{account_id}/datastorage/feedback/`). Do not submit feedback unless the user asks.

## More

- Recipes: https://www.forager.ai/docs/recipes/overview
- Choose an endpoint: https://www.forager.ai/docs/guides/choose-an-endpoint
- Filter IDs: https://www.forager.ai/docs/guides/find-filter-values
- Errors and rate limits: https://www.forager.ai/docs/errors-and-rate-limits
- Security, privacy and compliance (data sources, opt-out, lawful use): https://www.forager.ai/docs/security
- Docs index for agents: https://www.forager.ai/docs/llms.txt