$5 free Limited time. Sign up to activate. Get your $5 →
Free tool

Build a Forager API request

Pick an endpoint, fill in the parameters and copy the request in the language you use. Each one shows what comes back, what it costs in credits and where to run it for real.

Which endpoint?

Nothing is sent from this page and no key is entered here: the samples read your key and account ID from environment variables. Every sample response is fictional (example domains, 555 numbers, made-up names).

Person profile

POST /api/{account_id}/datastorage/person_detail_lookup/

The profile for one person: roles, education, skills and location.

1 credit · charged per request

Parameters

LinkedIn public identifier
The part of the profile URL after /in/.
Forager person ID(the other way to identify the person)
The id of a person record from an earlier lookup.

The request

cURL
curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/person_detail_lookup/" \
  -H "X-API-KEY: $FORAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "linkedin_public_identifier": "priya-example"
}'
Python
import os, requests

resp = requests.post(
    f"https://api-v2.forager.ai/api/{os.environ['FORAGER_ACCOUNT_ID']}/datastorage/person_detail_lookup/",
    headers={"X-API-KEY": os.environ["FORAGER_API_KEY"]},
    json={
      "linkedin_public_identifier": "priya-example"
    },
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch(
  `https://api-v2.forager.ai/api/${process.env.FORAGER_ACCOUNT_ID}/datastorage/person_detail_lookup/`,
  {
    method: "POST",
    headers: { "X-API-KEY": process.env.FORAGER_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      "linkedin_public_identifier": "priya-example"
    }),
  },
);
if (!resp.ok) throw new Error(`Forager returned ${resp.status}`);
console.log(await resp.json());

Sample response (fictional) · HTTP 200

{
  "id": 48213907,
  "full_name": "Priya Example",
  "first_name": "Priya",
  "last_name": "Example",
  "headline": "Head of Revenue Operations at Northwind Example Labs",
  "location": [
    {
      "id": 4671,
      "name": "Austin, Texas, United States"
    }
  ],
  "linkedin_info": {
    "public_identifier": "priya-example",
    "public_profile_url": "https://www.linkedin.com/in/priya-example/"
  },
  "roles": [
    {
      "role_title": "Head of Revenue Operations",
      "organization_name": "Northwind Example Labs",
      "start_date": "2023-02",
      "end_date": null,
      "is_current": true
    }
  ],
  "educations": [
    {
      "school_name": "Example State University",
      "degree": "BSc",
      "field_of_study": "Economics",
      "end_date": "2014"
    }
  ],
  "skills": [
    {
      "name": "Revenue operations"
    },
    {
      "name": "Salesforce administration"
    }
  ]
}
id
The person_id every contact lookup takes.
linkedin_info.public_identifier
The handle; also accepted by every contact lookup.
roles[]
Current and past positions, is_current marks the present one.

Pass id (as person_id) or the handle to the mobile, work email and personal email lookups.

Run this for real: Person enrichment API reference (opens in a new tab)

Mobile number

POST /api/{account_id}/datastorage/person_contacts_lookup/phone_numbers/

The mobile number for a person.

15 credits · charged only when data comes back

Parameters

LinkedIn public identifier
The part of the profile URL after /in/.
Forager person ID(the other way to identify the person)
The id of a person record from an earlier lookup.

The request

cURL
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": "priya-example"
}'
Python
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": "priya-example"
    },
)
resp.raise_for_status()
print(resp.json())
JavaScript
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": "priya-example"
    }),
  },
);
if (!resp.ok) throw new Error(`Forager returned ${resp.status}`);
console.log(await resp.json());

Sample response (fictional) · HTTP 200

[
  {
    "phone_number": "+15550100142"
  }
]
phone_number
E.164 format, ready to dial. An empty list is a miss and costs 0 credits.

Run this for real: Mobile numbers API reference (opens in a new tab)

Work email

POST /api/v2/{account_id}/datastorage/person_contacts_lookup/work_emails/

An address at the person’s current employer, checked for deliverability. The lookup runs as a job.

5 credits · charged only when data comes back

Parameters

Name and company domain
A full URL is accepted and reduced to its domain.
LinkedIn public identifier(the other way to identify the person)
Name and employer domain are taken from the Forager dataset.
Optional. Forager POSTs the result here when the job finishes, so you need not poll.

The request

cURL
curl -X POST "https://api-v2.forager.ai/api/v2/$FORAGER_ACCOUNT_ID/datastorage/person_contacts_lookup/work_emails/" \
  -H "X-API-KEY: $FORAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Priya",
  "last_name": "Example",
  "domain": "northwind.example"
}'
Python
import os, requests

resp = requests.post(
    f"https://api-v2.forager.ai/api/v2/{os.environ['FORAGER_ACCOUNT_ID']}/datastorage/person_contacts_lookup/work_emails/",
    headers={"X-API-KEY": os.environ["FORAGER_API_KEY"]},
    json={
      "first_name": "Priya",
      "last_name": "Example",
      "domain": "northwind.example"
    },
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch(
  `https://api-v2.forager.ai/api/v2/${process.env.FORAGER_ACCOUNT_ID}/datastorage/person_contacts_lookup/work_emails/`,
  {
    method: "POST",
    headers: { "X-API-KEY": process.env.FORAGER_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      "first_name": "Priya",
      "last_name": "Example",
      "domain": "northwind.example"
    }),
  },
);
if (!resp.ok) throw new Error(`Forager returned ${resp.status}`);
console.log(await resp.json());

Sample response (fictional) · HTTP 202

{
  "job_id": "6f1c2a0e-0000-4000-8000-000000000042",
  "status": "pending",
  "status_check_url": "https://api-v2.forager.ai/api/v2/1234/datastorage/person_contacts_lookup/work_emails/6f1c2a0e-0000-4000-8000-000000000042/",
  "webhook_url": null
}
job_id
The lookup runs asynchronously; this is its id.
status_check_url
Poll it until status is completed or failed. Polling is free.
status
pending here; completed carries the emails.

Credits are charged once, only when an address is found.

Run this for real: Work emails API reference (opens in a new tab)

Personal email

POST /api/{account_id}/datastorage/person_contacts_lookup/personal_emails/

Addresses on consumer mail providers for a person.

5 credits · charged only when data comes back

Parameters

LinkedIn public identifier
The part of the profile URL after /in/.
Forager person ID(the other way to identify the person)
The id of a person record from an earlier lookup.

The request

cURL
curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/person_contacts_lookup/personal_emails/" \
  -H "X-API-KEY: $FORAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "linkedin_public_identifier": "priya-example"
}'
Python
import os, requests

resp = requests.post(
    f"https://api-v2.forager.ai/api/{os.environ['FORAGER_ACCOUNT_ID']}/datastorage/person_contacts_lookup/personal_emails/",
    headers={"X-API-KEY": os.environ["FORAGER_API_KEY"]},
    json={
      "linkedin_public_identifier": "priya-example"
    },
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch(
  `https://api-v2.forager.ai/api/${process.env.FORAGER_ACCOUNT_ID}/datastorage/person_contacts_lookup/personal_emails/`,
  {
    method: "POST",
    headers: { "X-API-KEY": process.env.FORAGER_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      "linkedin_public_identifier": "priya-example"
    }),
  },
);
if (!resp.ok) throw new Error(`Forager returned ${resp.status}`);
console.log(await resp.json());

Sample response (fictional) · HTTP 200

[
  {
    "email": "priya.example@example.com",
    "email_type": "personal",
    "validation_status": "valid"
  }
]
email
Only addresses on free webmail providers come back.
validation_status
Whether the address passed validation.

Run this for real: Personal emails API reference (opens in a new tab)

Person by email

POST /api/{account_id}/datastorage/person_detail_reverse_lookup/by_email/

The person behind a personal email address: the same profile shape as the person lookup.

5 credits · charged per request

Parameters

Required. The personal email address of the person.

The request

cURL
curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/person_detail_reverse_lookup/by_email/" \
  -H "X-API-KEY: $FORAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "priya.example@example.com"
}'
Python
import os, requests

resp = requests.post(
    f"https://api-v2.forager.ai/api/{os.environ['FORAGER_ACCOUNT_ID']}/datastorage/person_detail_reverse_lookup/by_email/",
    headers={"X-API-KEY": os.environ["FORAGER_API_KEY"]},
    json={
      "email": "priya.example@example.com"
    },
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch(
  `https://api-v2.forager.ai/api/${process.env.FORAGER_ACCOUNT_ID}/datastorage/person_detail_reverse_lookup/by_email/`,
  {
    method: "POST",
    headers: { "X-API-KEY": process.env.FORAGER_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      "email": "priya.example@example.com"
    }),
  },
);
if (!resp.ok) throw new Error(`Forager returned ${resp.status}`);
console.log(await resp.json());

Sample response (fictional) · HTTP 200

{
  "id": 48213907,
  "full_name": "Priya Example",
  "first_name": "Priya",
  "last_name": "Example",
  "headline": "Head of Revenue Operations at Northwind Example Labs",
  "location": [
    {
      "id": 4671,
      "name": "Austin, Texas, United States"
    }
  ],
  "linkedin_info": {
    "public_identifier": "priya-example",
    "public_profile_url": "https://www.linkedin.com/in/priya-example/"
  },
  "roles": [
    {
      "role_title": "Head of Revenue Operations",
      "organization_name": "Northwind Example Labs",
      "start_date": "2023-02",
      "end_date": null,
      "is_current": true
    }
  ],
  "educations": [
    {
      "school_name": "Example State University",
      "degree": "BSc",
      "field_of_study": "Economics",
      "end_date": "2014"
    }
  ],
  "skills": [
    {
      "name": "Revenue operations"
    },
    {
      "name": "Salesforce administration"
    }
  ]
}
id
Use it as person_id in the contact lookups.
headline
Role and employer in one line.

The profile carries the handle and person ID, so the contact lookups follow from here.

Run this for real: Reverse email lookup API reference (opens in a new tab)

Every request is a POST to https://api-v2.forager.ai with your API key in the X-API-KEY header and your account ID in the path. Paths and parameters here are read from the API reference’s OpenAPI file; fields the playground leaves out are documented on each endpoint’s reference page.

Run it on your own records

  • $5 free credits
  • No credit card
  • Run your sample
Start building

Put people, company and job data your users can act on inside your product

Send us a list. We run it, show you what we find, then talk volume and terms.

  • $5 free credits
  • No credit card
  • Run your sample
Platforms and teams that build on Forager
  • Clay
  • Juicebox
  • Nooks
  • Andela
  • HubSpot
  • SeekOut