cURL quickstart for the Forager API

Forager is a REST API, so everything on this page is a plain curl call: one person lookup, the responses to handle when a call fails, and one asynchronous work email lookup that you submit, poll and read. You need curl and, for the polling loop, jq.

Set your key and Account ID

Create a key on the API page of the Forager Web App and copy your Account ID from My Account. Export both; every call below reads them from the environment, never from the command line history.

export FORAGER_API_KEY="your-api-key"
export FORAGER_ACCOUNT_ID="your-account-id"

The key travels in the X-API-KEY header. 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.

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

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 the responses that are not a 200

Add -w '\n%{http_code}\n' to see the status code with the body, then branch on it. The documented cases:

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 the `Retry-After` header when one 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.

This script retries a 429 twice, with a growing wait, and prints everything else:

forager_post() {  # usage: forager_post <path-after-/api/> '<json body>'
  local attempt=0 wait=2 code body
  while :; do
    body=$(curl -sS -X POST "https://api-v2.forager.ai/api/$1" \
      -H "X-API-KEY: $FORAGER_API_KEY" -H "Content-Type: application/json" \
      -d "$2" -w '\n%{http_code}')
    code=${body##*$'\n'}; body=${body%$'\n'*}
    case "$code" in
      2??) printf '%s\n' "$body"; return 0 ;;
      403) echo "forager: check FORAGER_API_KEY and FORAGER_ACCOUNT_ID: $body" >&2; return 1 ;;
      429) attempt=$((attempt + 1)); [ "$attempt" -gt 2 ] && { echo "forager: still rate limited" >&2; return 1; }
           sleep "$wait"; wait=$((wait * 2)) ;;
      402) echo "forager: out of credits (status not yet documented): $body" >&2; return 1 ;;
      *)   echo "forager: HTTP $code: $body" >&2; return 1 ;;
    esac
  done
}

forager_post "$FORAGER_ACCOUNT_ID/datastorage/person_detail_lookup/" '{"linkedin_public_identifier": "jane-doe-example"}'

An empty list or an empty body on a contact lookup is a result, not an error: the person was found but no number or address is on record.

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.

JOB=$(forager_post "v2/$FORAGER_ACCOUNT_ID/datastorage/person_contacts_lookup/work_emails/" \
  '{"first_name": "Jane", "last_name": "Doe", "domain": "acme.com"}')
JOB_ID=$(printf '%s' "$JOB" | jq -r .job_id)
echo "$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.

while :; do
  resp=$(curl -sS -D - "https://api-v2.forager.ai/api/v2/$FORAGER_ACCOUNT_ID/datastorage/person_contacts_lookup/work_emails/$JOB_ID/" \
    -H "X-API-KEY: $FORAGER_API_KEY")
  body=$(printf '%s' "$resp" | sed '1,/^\r\{0,1\}$/d')
  status=$(printf '%s' "$body" | jq -r .status)
  case "$status" in
    completed|failed) printf '%s\n' "$body" | jq .; break ;;
  esac
  wait=$(printf '%s' "$resp" | awk 'tolower($1)=="retry-after:" {gsub("\r","",$2); print $2}')
  sleep "${wait:-5}"
done

A completed job has result set to found (with emails) or not_found. A failed job has an error_code such as person_not_found or no_current_employer.

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.

Next steps

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.

Python quickstart

The same walkthrough with requests.

Node.js quickstart

The same walkthrough with fetch.

Get started

Contact data

People and companies

Account and billing

Production

Help

Coming soon

cURL quickstart for the Forager API

Next steps

Choose the right endpoint

Errors and rate limits

Python quickstart

Node.js quickstart

​Next steps

Choose the right endpoint

Errors and rate limits

Python quickstart

Node.js quickstart

Next steps