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

# Phone number API for dialers

> Turn a LinkedIn profile URL into a phone number for your dialer with the Forager phone numbers lookup, with error and credit handling.

```text Recipe prompt theme={"theme":{"light":"github-light","dark":"github-dark"}}
Implement this recipe in my project: https://www.forager.ai/docs/recipes/dialer-mobile.md

Build a server-side function that takes a LinkedIn profile URL, extracts the LinkedIn public identifier, and calls the Forager phone numbers lookup. Return the list of phone numbers to the dialer UI. Handle an empty result, a 403 from a bad key, and a 429 with backoff. Keep the API key server-side in FORAGER_API_KEY and the account in FORAGER_ACCOUNT_ID, never in the browser. Add tests that stub the HTTP call for each case.
```

![Phone number API flow for dialers: a profile URL goes into Forager and a phone number comes back](https://mintcdn.com/forager/4wLamkiYCyhA7GPC/images/recipes/phone-number-api-dialer-lookup.svg?fit=max\&auto=format\&n=4wLamkiYCyhA7GPC\&q=85\&s=897c90663298026f7c02e7c4d924db0f)

## What you'll build

A small backend endpoint for your dialer. A rep opens a prospect, the dialer sends the prospect's LinkedIn profile URL to your server, and your server returns the phone numbers Forager has for that person.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
  A[Dialer] --> B[Your server]
  B --> C[Extract identifier]
  C --> D[Forager phone lookup]
  D --> E[Numbers to dialer]
```

> [!NOTE]
>
> The response lists `phone_number` values and nothing else. The API reference does not document a line-type field, so this recipe does not promise mobile-only results.

## Steps

**1. Get your credentials**

Create an API key and note your Account ID. See [Authentication](https://www.forager.ai/docs/api-overview/authentication.md). Export them on your server as `FORAGER_API_KEY` and `FORAGER_ACCOUNT_ID`.

**2. Extract the LinkedIn public identifier**

The lookup takes `linkedin_public_identifier`, the slug in `linkedin.com/in/<slug>/`. Parse it from the profile URL.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from urllib.parse import urlparse

def public_identifier(profile_url: str) -> str | None:
    parts = [p for p in urlparse(profile_url).path.split("/") if p]
    return parts[1] if len(parts) > 1 and parts[0] == "in" else None
```

**3. Call the phone numbers lookup**

Send a `POST` to [Phone numbers lookup](https://www.forager.ai/docs/openapi/phones/datastorage_person_contacts_lookup_phone_numbers_create.md).

```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": "jane-doe-example"}'
```

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

url = (
    f"https://api-v2.forager.ai/api/{os.environ['FORAGER_ACCOUNT_ID']}"
    "/datastorage/person_contacts_lookup/phone_numbers/"
)
r = requests.post(
    url,
    headers={"X-API-KEY": os.environ["FORAGER_API_KEY"]},
    json={"linkedin_public_identifier": "jane-doe-example"},
    timeout=30,
)
r.raise_for_status()
numbers = [row["phone_number"] for row in r.json()]
```

```javascript JavaScript (fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
const url =
  `https://api-v2.forager.ai/api/${process.env.FORAGER_ACCOUNT_ID}` +
  "/datastorage/person_contacts_lookup/phone_numbers/";
const res = await fetch(url, {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.FORAGER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ linkedin_public_identifier: "jane-doe-example" }),
});
if (!res.ok) throw new Error(`Forager ${res.status}`);
const numbers = (await res.json()).map((row) => row.phone_number);
```

**Example response (illustrative values)**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[{ "phone_number": "+1 555-0100" }, { "phone_number": "+1 555-0101" }]
```

**4. Show the numbers and report the outcome**

Return the numbers to the dialer. After the call, you can tell Forager whether a number was `connected` or `disconnected` with [Submit phone-number verification feedback](https://www.forager.ai/docs/openapi/feedback/datastorage_feedback_phone_numbers_create.md). It takes `phone_number` and `contact_status`.

## Handle the edge cases

* **Not found.** An empty list means no numbers. Show "no number found" and let the rep skip the call.
* **403.** The key is missing, invalid or not allowed. Check `FORAGER_API_KEY` and `FORAGER_ACCOUNT_ID`, and do not retry.
* **429.** Back off and retry. See [errors and rate limits](https://www.forager.ai/docs/errors-and-rate-limits.md).
* **Credits.** A phone number lookup costs 15 credits per lookup. Cache results per person so a rep reopening a prospect does not spend again. See [credit pricing](https://www.forager.ai/docs/api-overview/credit-pricing.md).

## Related

> [card] [Find phone numbers](https://www.forager.ai/docs/guides/find-phone-numbers.md)
>
> The guide behind this recipe.

> [card] [Phone numbers lookup](https://www.forager.ai/docs/openapi/phones/datastorage_person_contacts_lookup_phone_numbers_create.md)
>
> Request and response reference.

> [card] [Enrich a contact](https://www.forager.ai/docs/guides/enrich-a-contact.md)
>
> Get the full person record.


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