Phone number API for dialers

Recipe prompt

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.

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.

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

Get your credentials

Create an API key and note your Account ID. See Authentication. Export them on your server as FORAGER_API_KEY and FORAGER_ACCOUNT_ID.

Extract the LinkedIn public identifier

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

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

Call the phone numbers lookup

Send a POST to Phone numbers lookup.

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"}'

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()]

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)

[{ "phone_number": "+1 555-0100" }, { "phone_number": "+1 555-0101" }]

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

Find phone numbers

The guide behind this recipe.

Phone numbers lookup

Request and response reference.

Enrich a contact

Get the full person record.

Recipes

Sales and dialer platforms

Recruiting platforms

Data and product teams

AI agents

Sample apps

More examples

Phone number API for dialers

What you’ll build

Steps

Handle the edge cases

Find phone numbers

Phone numbers lookup

Enrich a contact

​What you’ll build

​Steps

​Handle the edge cases

​Related

Find phone numbers

Phone numbers lookup

Enrich a contact

What you’ll build

Steps

Handle the edge cases

Related