Python quickstart for the Forager API

This quickstart calls the Forager REST API from Python with the requests library: one person lookup, a small client that handles the failure responses, and an asynchronous work email lookup that you submit, poll and read. No Forager package is needed, and none is published yet, so requests is the whole dependency list.

Install requests and set your credentials

pip install requests
export FORAGER_API_KEY="your-api-key"
export FORAGER_ACCOUNT_ID="your-account-id"

Create the key on the API page of the Forager Web App and copy the Account ID from My Account. The code reads both from the environment; never put the key in source files or logs. See API key authentication.

Run your first lookup

A person lookup costs 1 credit and takes a LinkedIn public identifier (the slug after /in/) or a Forager person_id.

first_lookup.py

import os
import requests

BASE = "https://api-v2.forager.ai/api"
ACCOUNT = os.environ["FORAGER_ACCOUNT_ID"]
HEADERS = {"X-API-KEY": os.environ["FORAGER_API_KEY"]}

resp = requests.post(
    f"{BASE}/{ACCOUNT}/datastorage/person_detail_lookup/",
    headers=HEADERS,
    json={"linkedin_public_identifier": "jane-doe-example"},
    timeout=30,
)
resp.raise_for_status()
person = resp.json()
print(person["id"], person["full_name"], person["headline"])

The response is one person record. Trimmed, with fictional values:

Response (illustrative)

{
  "id": 48213,
  "full_name": "Jane Doe",
  "headline": "Head of Data at Acme Example",
  "linkedin_info": { "public_identifier": "jane-doe-example" },
  "roles": [
    { "role_title": "Head of Data", "is_current": true, "organization": { "name": "Acme Example", "domain": "acme.com" } }
  ]
}

Keep id: the phone and personal email lookups take it as person_id.

Handle 403, 429 and running out of credits

raise_for_status() turns every error into the same exception. The cases below need different handling, so wrap the call in a small client:

Status	What happened	What to do
`403`	`{"detail": "Authentication credentials were not provided."}`: the header is missing or the key is wrong, or the key cannot use this Account ID.	Fix the credentials. Never retry in a loop.
`429`	Rate limit. Documented for the autocomplete and feedback endpoints; the single work email lookup is also limited for interactive use.	Wait, then retry with backoff. Use `Retry-After` when it is sent.
Out of credits	A bulk work email batch your balance cannot cover is rejected and nothing is charged. The status code and body are not documented yet.	Buy credits in the Web App, then resubmit.

forager_client.py

import os
import time
import requests

BASE = "https://api-v2.forager.ai/api"
ACCOUNT = os.environ["FORAGER_ACCOUNT_ID"]
HEADERS = {"X-API-KEY": os.environ["FORAGER_API_KEY"]}


class ForagerAuthError(Exception):
    """403: the API key or Account ID is wrong. Do not retry."""


class ForagerCreditsError(Exception):
    """The account has no credits left for this request."""


class ForagerRateLimited(Exception):
    """429 after every retry."""


def forager(method, path, *, json=None, params=None, retries=3):
    """Call the Forager API. `path` is everything after /api/, for example
    f"{ACCOUNT}/datastorage/person_detail_lookup/"."""
    wait = 2.0
    for attempt in range(retries + 1):
        resp = requests.request(method, f"{BASE}/{path}", headers=HEADERS,
                                json=json, params=params, timeout=30)
        if resp.status_code == 403:
            raise ForagerAuthError(resp.text)
        if resp.status_code == 402:
            # Not documented by Forager yet; kept as a guard for an out-of-credits rejection.
            raise ForagerCreditsError(resp.text)
        if resp.status_code == 429 and attempt < retries:
            time.sleep(float(resp.headers.get("Retry-After", wait)))
            wait *= 2
            continue
        if resp.status_code == 429:
            raise ForagerRateLimited(resp.text)
        resp.raise_for_status()
        return resp
    raise AssertionError("unreachable")


if __name__ == "__main__":
    person = forager("POST", f"{ACCOUNT}/datastorage/person_detail_lookup/",
                     json={"linkedin_public_identifier": "jane-doe-example"}).json()
    print(person["full_name"])

An empty list on a contact lookup is a result, not an error: the person was found but no number or address is on record. requests raises on a 2xx with an empty body only when you call .json(), so check resp.content first for those endpoints.

Submit an async work email lookup

The work email lookup answers 202 at once with a job_id, because verifying an address takes longer than a request should wait. Identify the person by name and company domain, or by LinkedIn public identifier.

from forager_client import ACCOUNT, forager

submitted = forager(
    "POST",
    f"v2/{ACCOUNT}/datastorage/person_contacts_lookup/work_emails/",
    json={"first_name": "Jane", "last_name": "Doe", "domain": "acme.com"},
).json()
job_id = submitted["job_id"]

202 response (illustrative)

{
  "job_id": "2b7e1a40-3c5d-4f6e-8a9b-0c1d2e3f4a5b",
  "status": "queued",
  "status_check_url": "https://api-v2.forager.ai/api/v2/123456/datastorage/person_contacts_lookup/work_emails/2b7e1a40-3c5d-4f6e-8a9b-0c1d2e3f4a5b/",
  "webhook_url": ""
}

Poll until the job is terminal

Poll the job result until status is completed or failed. Polling is free. While the job is still running the response carries a Retry-After header that says how long to wait.

import time

def wait_for_work_email(job_id, max_wait=300):
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        resp = forager("GET", f"v2/{ACCOUNT}/datastorage/person_contacts_lookup/work_emails/{job_id}/")
        job = resp.json()
        if job["status"] in ("completed", "failed"):
            return job
        time.sleep(float(resp.headers.get("Retry-After", 5)))
    raise TimeoutError(f"work email job {job_id} still {job['status']} after {max_wait}s")

job = wait_for_work_email(job_id)
if job["status"] == "failed":
    print("failed:", job["error_code"])        # e.g. person_not_found, no_current_employer
elif job["result"] == "found":
    print("work email:", job["emails"][0])     # shortest confirmed address first
else:
    print("no work email on record")

Completed job (illustrative)

{
  "job_id": "2b7e1a40-3c5d-4f6e-8a9b-0c1d2e3f4a5b",
  "status": "completed",
  "result": "found",
  "emails": ["jane.doe@acme.com"],
  "error_code": null,
  "person_id": 48213
}

5 credits are charged only when result is found. To skip polling, send a webhook_url with the submit request and Forager POSTs the result there. For more than a handful of people, use the bulk lookup instead of a loop of single lookups.

Test without spending credits

Mock the HTTP layer in your tests so they never reach api-v2.forager.ai. With requests, the responses library or unittest.mock.patch("requests.request") is enough: return a 403 to check ForagerAuthError, a 429 then a 200 to check the retry, and a completed job body to check the polling loop.

Next steps

Enrich a CSV of LinkedIn URLs

A complete Python script built on this client.

Choose the right endpoint

Match what you have to the endpoint you need, with each call’s credit cost.

Errors and rate limits

Every documented status code and limit.

Node.js quickstart

The same walkthrough with fetch.

Get started

Contact data

People and companies

Account and billing

Production

Help

Coming soon

Python quickstart for the Forager API

Test without spending credits

Next steps

Enrich a CSV of LinkedIn URLs

Choose the right endpoint

Errors and rate limits

Node.js quickstart

​Test without spending credits

​Next steps

Enrich a CSV of LinkedIn URLs

Choose the right endpoint

Errors and rate limits

Node.js quickstart

Test without spending credits

Next steps