Node.js quickstart for the Forager API

This quickstart calls the Forager REST API from Node.js with the built-in fetch (Node 18 or newer): 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 there is nothing to install.

Set your credentials

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 process.env; keep the key out of source files, logs and anything that ships to a browser. 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.mjs

const BASE = "https://api-v2.forager.ai/api";
const ACCOUNT = process.env.FORAGER_ACCOUNT_ID;
const HEADERS = { "X-API-KEY": process.env.FORAGER_API_KEY, "Content-Type": "application/json" };

const resp = await fetch(`${BASE}/${ACCOUNT}/datastorage/person_detail_lookup/`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ linkedin_public_identifier: "jane-doe-example" }),
});
if (!resp.ok) throw new Error(`Forager returned ${resp.status}: ${await resp.text()}`);
const person = await resp.json();
console.log(person.id, person.full_name, person.headline);

Run it with node first-lookup.mjs. 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

resp.ok is false for every error. The cases below need different handling, so wrap fetch 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.mjs

const BASE = "https://api-v2.forager.ai/api";
export const ACCOUNT = process.env.FORAGER_ACCOUNT_ID;
const HEADERS = { "X-API-KEY": process.env.FORAGER_API_KEY, "Content-Type": "application/json" };

export class ForagerError extends Error {
  constructor(kind, status, body) {
    super(`Forager ${kind} (HTTP ${status}): ${body}`);
    this.kind = kind;     // "auth" | "credits" | "rate_limited" | "http"
    this.status = status;
  }
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

/** Call the Forager API. `path` is everything after /api/, for example
 *  `${ACCOUNT}/datastorage/person_detail_lookup/`. Returns the Response. */
export async function forager(method, path, { json, retries = 3 } = {}) {
  let wait = 2000;
  for (let attempt = 0; attempt <= retries; attempt++) {
    const resp = await fetch(`${BASE}/${path}`, {
      method,
      headers: HEADERS,
      body: json === undefined ? undefined : JSON.stringify(json),
    });
    if (resp.status === 403) throw new ForagerError("auth", 403, await resp.text());
    // 402 is not documented by Forager yet; kept as a guard for an out-of-credits rejection.
    if (resp.status === 402) throw new ForagerError("credits", 402, await resp.text());
    if (resp.status === 429) {
      if (attempt === retries) throw new ForagerError("rate_limited", 429, await resp.text());
      const retryAfter = Number(resp.headers.get("retry-after"));
      await sleep(retryAfter > 0 ? retryAfter * 1000 : wait);
      wait *= 2;
      continue;
    }
    if (!resp.ok) throw new ForagerError("http", resp.status, await resp.text());
    return resp;
  }
}

/** Parse a JSON body, treating an empty 2xx body as an empty result. */
export async function body(resp) {
  const text = await resp.text();
  return text ? JSON.parse(text) : null;
}

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.

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.

import { ACCOUNT, forager, body } from "./forager-client.mjs";

const submitted = await body(
  await forager("POST", `v2/${ACCOUNT}/datastorage/person_contacts_lookup/work_emails/`, {
    json: { first_name: "Jane", last_name: "Doe", domain: "acme.com" },
  }),
);
const jobId = 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.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForWorkEmail(jobId, maxWaitMs = 300_000) {
  const deadline = Date.now() + maxWaitMs;
  let job;
  while (Date.now() < deadline) {
    const resp = await forager("GET", `v2/${ACCOUNT}/datastorage/person_contacts_lookup/work_emails/${jobId}/`);
    job = await body(resp);
    if (job.status === "completed" || job.status === "failed") return job;
    const retryAfter = Number(resp.headers.get("retry-after"));
    await sleep(retryAfter > 0 ? retryAfter * 1000 : 5000);
  }
  throw new Error(`work email job ${jobId} still ${job?.status} after ${maxWaitMs} ms`);
}

const job = await waitForWorkEmail(jobId);
if (job.status === "failed") console.log("failed:", job.error_code);   // e.g. person_not_found
else if (job.result === "found") console.log("work email:", job.emails[0]);
else console.log("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

Stub fetch in your tests so they never reach api-v2.forager.ai. In Node 18 and later, globalThis.fetch can be replaced with a function that returns new Response(JSON.stringify(body), { status, headers }): return a 403 to check the auth error, a 429 then a 200 to check the retry, and a completed job body to check the polling loop.

Next steps

Nightly job postings sync

A complete Node.js 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.

Python quickstart

The same walkthrough with requests.

Get started

Contact data

People and companies

Account and billing

Production

Help

Coming soon

Node.js quickstart for the Forager API

Test without spending credits

Next steps

Nightly job postings sync

Choose the right endpoint

Errors and rate limits

Python quickstart

​Test without spending credits

​Next steps

Nightly job postings sync

Choose the right endpoint

Errors and rate limits

Python quickstart

Test without spending credits

Next steps