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

# Forager API quickstart

> Quickstart: look up a person's phone numbers from a LinkedIn public identifier with one Forager API request, in about 5 minutes.

In about 5 minutes you'll look up the phone numbers for one person from their LinkedIn public identifier, the part of a profile URL after `/in/`.

![A LinkedIn profile URL goes into Forager and phone numbers come back](https://mintcdn.com/forager/OnhSHNo_LBQ7yKjR/images/illustrations/linkedin-profile-to-phone-number-lookup-animation.svg?fit=max\&auto=format\&n=OnhSHNo_LBQ7yKjR\&q=85\&s=281d1b42e95b75047c078c3637d63000)

> [!TIP]
>
> Using a coding agent? Paste this instead and it will do the steps for you:
>
> ```text Setup prompt theme={"theme":{"light":"github-light","dark":"github-dark"}}
> Read https://www.forager.ai/docs/guides/agent-quickstart.md and follow it to add the Forager API to this project. Keep my API key server-side in FORAGER_API_KEY and FORAGER_ACCOUNT_ID.
> ```

**1. Get your API key and Account ID**

Create a free account at [app.forager.ai](https://app.forager.ai/sign-up). Then:

* Create a key on the **[API](https://app.forager.ai/keys)** page.
* Copy your **Account ID** from **[My Account](https://app.forager.ai/profile)**.

Set both in your terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export FORAGER_API_KEY="your-api-key"
export FORAGER_ACCOUNT_ID="your-account-id"
```

Keep the key server-side. Don't commit it or put it in browser code. See [authentication](https://www.forager.ai/docs/api-overview/authentication.md).

**2. Look up phone numbers**

Send a `POST` to the [phone number lookup](https://www.forager.ai/docs/openapi/phones/datastorage_person_contacts_lookup_phone_numbers_create.md) with a LinkedIn public identifier. You can send a Forager `person_id` instead.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/person_contacts_lookup/phone_numbers/" \
  -H "X-API-KEY: $FORAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkedin_public_identifier": "billgates"}'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os, requests

resp = requests.post(
    f"https://api-v2.forager.ai/api/{os.environ['FORAGER_ACCOUNT_ID']}/datastorage/person_contacts_lookup/phone_numbers/",
    headers={"X-API-KEY": os.environ["FORAGER_API_KEY"]},
    json={"linkedin_public_identifier": "billgates"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const resp = await fetch(
  `https://api-v2.forager.ai/api/${process.env.FORAGER_ACCOUNT_ID}/datastorage/person_contacts_lookup/phone_numbers/`,
  {
    method: "POST",
    headers: { "X-API-KEY": process.env.FORAGER_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ linkedin_public_identifier: "billgates" }),
  },
);
if (!resp.ok) throw new Error(`Forager returned ${resp.status}`);
console.log(await resp.json());
```

Each phone number lookup uses 15 credits. See [credits and pricing](https://www.forager.ai/docs/api-overview/credit-pricing.md).

**3. Read the response**

The response is a list of phone numbers. Each item has a `phone_number` field.

```json Example response (illustrative values) theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  { "phone_number": "+12025550142" },
  { "phone_number": "+12025550187" }
]
```

If the key is missing or wrong, you get a `403`:

| Status | Message | What to do |
| - | - | - |
| `403` | `Authentication credentials were not provided.` | Check the `X-API-KEY` header and the key value. |
| `403` | `Forbidden` | The key can't access this resource. Check the Account ID in the path. |

See [API errors and rate limits](https://www.forager.ai/docs/errors-and-rate-limits.md) for the errors documented so far and their response bodies.

## Go deeper in your language

The [cURL](https://www.forager.ai/docs/quickstarts/curl.md), [Python](https://www.forager.ai/docs/quickstarts/python.md) and [Node.js](https://www.forager.ai/docs/quickstarts/node.md) quickstarts repeat these steps with a small client that handles `403` and `429`, then submit and poll an asynchronous work email lookup.

## Build your next request

Pick an endpoint and fill in the parameters to get the matching cURL, Python or JavaScript. The samples read `FORAGER_API_KEY` and `FORAGER_ACCOUNT_ID` from your environment; nothing is sent from this page.

**POST**

Cost: . Nothing is sent from this page.

<pre />

## Next steps

> [card] [Choose the right endpoint](https://www.forager.ai/docs/guides/choose-an-endpoint.md)
>
> Match what you have to what you need, with the cost of each call.

> [card] [Recipes](https://www.forager.ai/docs/recipes/overview.md)
>
> End-to-end builds for dialers, CRMs, recruiting and data teams.

> [card] [Try it in the API reference](https://www.forager.ai/docs/openapi/phones/datastorage_person_contacts_lookup_phone_numbers_create.md)
>
> Send the same request from your browser.

> [card] [Postman collection](https://www.forager.ai/docs/postman/forager-api.postman_collection.json)
>
> Every operation, ready to import. Set the `apiKey` and `accountId` variables.


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