Descovo

// NODE.JS GUIDE

Contact enrichment API in Node.js and TypeScript, with built-in fetch

Updated November 20, 2026

You can call the Descovo contact enrichment API from Node.js or TypeScript with the built-in fetch and one bearer key; there is no package to install. This guide builds a small typed helper, counts and searches people, reveals a work email for 2 credits when found, runs a bulk job of up to 2,000 profiles, and handles errors.

Set up: one key, one typed helper

Create a key in the dashboard and export it as DESCOVO_API_KEY. Node 18 or later has fetch built in; run the TypeScript files with npx tsx file.ts, or drop the type annotations for plain JavaScript. Every route lives under https://api.descovo.com/v1 and takes Authorization: Bearer <key>. Every successful response has the same shape: data with the result, and credits with what the call cost.

client.ts
const API = "https://api.descovo.com/v1";

export class DescovoError extends Error {
  status: number;
  code: string | undefined;

  constructor(status: number, code: string | undefined, message: string | undefined) {
    super(`${status} ${code}: ${message}`);
    this.status = status;
    this.code = code;
  }
}

type Credits = { charged?: number; available?: number | null };

export async function call<T>(method: "GET" | "POST", path: string, body?: unknown): Promise<{ data: T; credits: Credits }> {
  const res = await fetch(`${API}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.DESCOVO_API_KEY}`,
      ...(body ? { "Content-Type": "application/json" } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const payload = await res.json();
  if (!res.ok) throw new DescovoError(res.status, payload.error?.code, payload.error?.message);
  return { data: payload.data as T, credits: payload.credits ?? {} };
}

const { data: balance } = await call<{ available: number }>("GET", "/credits");
console.log("credits available:", balance.available);

GET https://api.descovo.com/v1/credits is free and returns your balance, so it is a safe first call to confirm the key works. Keep the key on the server: never ship it to a browser.

Count, then search

https://api.descovo.com/v1/people/count is free; https://api.descovo.com/v1/people/search costs 1 credit per person returned. The count comes back in totalProfilesFound, so you know what a search will cost before you run it. The company goes in top-level currentCompanies so the title must hold at that same job.

search.ts
type Person = { name?: string; primary_slug?: string };

const filters = {
  searchParams: {
    jobTitleV3: { anyOf: [{ type: "plain", term: "Account Executive" }] },
  },
  currentCompanies: [{ domain: "ramp.com" }],
};

// 1. Count first. It is free.
const { data: count } = await call<{ totalProfilesFound: number }>("POST", "/people/count", filters);
console.log("matches:", count.totalProfilesFound);

// 2. Then fetch only as many people as you will use. Each one is charged.
const { data: page, credits } = await call<{ data: Person[] }>("POST", "/people/search", { ...filters, pageSize: 10 });
const people = page.data;
console.log(people.length, "people for", credits.charged, "credits");

To describe people in a sentence instead, post { query: "..." } to /people/ask: 2 credits to read the question plus 1 per result.

Reveal an email or phone for one person

https://api.descovo.com/v1/contacts/reveal takes a LinkedIn profile URL. Search results carry the person's slug in primary_slug; the URL is https://www.linkedin.com/in/<slug>. A work email costs 2 credits and a direct phone 3, and credits.charged is zero when nothing is found.

reveal.ts
async function reveal(linkedinUrl: string, phone = false) {
  return call<unknown>("POST", "/contacts/reveal", {
    linkedinUrl,
    enrichmentType: { getWorkEmails: true, getPersonalEmails: false, getPhoneNumbers: phone },
  });
}

for (const person of people) {
  if (!person.primary_slug) continue;
  const { data, credits } = await reveal(`https://www.linkedin.com/in/${person.primary_slug}`);
  console.log(person.name, data, "charged:", credits.charged ?? 0);
}

Run a bulk job for a list

One call to https://api.descovo.com/v1/contacts/reveal/batch queues up to 2,000 profile URLs and returns a taskId. Credits are taken when you submit and anything not found is refunded when the job finishes. Polling is free.

bulk.ts
type PollPage = {
  done: boolean;
  nextCursor?: string | null;
  pageResults: {
    inputs: { linkedinUrl: { value: string } };
    outputs?: { emails?: { email: string }[] } | null;
  }[];
};

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
const urls = people.filter((p) => p.primary_slug).map((p) => `https://www.linkedin.com/in/${p.primary_slug}`);

const { data: task } = await call<{ taskId: string }>("POST", "/contacts/reveal/batch", {
  linkedinUrls: urls.slice(0, 2000),
  enrichmentTypes: { getWorkEmails: true, getPersonalEmails: false, getPhoneNumbers: false },
});

// Wait for the job to finish (results can also be read while it runs).
while (!(await call<PollPage>("POST", "/contacts/reveal/batch/poll", { taskId: task.taskId })).data.done) {
  await sleep(5000);
}

// Then read every page.
let cursor: string | null | undefined;
do {
  const { data } = await call<PollPage>("POST", "/contacts/reveal/batch/poll", {
    taskId: task.taskId,
    ...(cursor ? { cursor } : {}),
  });
  for (const row of data.pageResults) {
    console.log(row.inputs.linkedinUrl.value, (row.outputs?.emails ?? []).map((e) => e.email));
  }
  cursor = data.nextCursor;
} while (cursor);

Handle the four errors that matter

HTTP errors and what to do
StatusCodeWhat to do
400invalid_requestThe body does not match the route, for example an unknown field. Fix it; nothing was charged
401unauthorizedNo key, or a revoked key
402insufficient_creditsOut of credits. Stop and top up; retrying will not help
429rate_limitedToo fast. Wait and retry
errors.ts
try {
  await call("POST", "/contacts/reveal", { linkedinUrl, enrichmentType: { getWorkEmails: true } });
} catch (e) {
  if (!(e instanceof DescovoError)) throw e;
  if (e.status === 402) throw new Error("Out of credits");   // insufficient_credits: stop, do not retry
  if (e.status === 429) await sleep(5000);                    // rate_limited: wait, then retry
  else throw e;                                               // 400 invalid_request: fix the body; nothing was charged
}

Keep spend predictable

  • Count before you search, and set pageSize to the number of people you will actually use.
  • Ask only for the fields you need. Leaving getPhoneNumbers false keeps a reveal at the email price.
  • Read credits.charged on every response and stop when a budget is reached.
  • Use the bulk endpoint for lists: misses are refunded and repeats in the list are dropped.

Frequently asked questions

Is there a Descovo npm package?
No. The API is plain HTTPS with JSON bodies and a bearer key, so the fetch built into Node 18 and later is all you need. An OpenAPI document is published at https://api.descovo.com/v1/openapi.json if you want to generate a typed client.
Can I call the API from a browser?
Do not. A browser would expose your API key to every visitor. Call the API from your server and send your own front end only the results.
How do I know what a call cost?
Every successful response includes credits.charged, the credits that call used, and usually credits.available, your balance afterwards.
What happens when I run out of credits?
The API returns HTTP 402 with the code insufficient_credits. Retrying does not help; add credits or change plan first.
Can I try this for free?
Yes. A new account gets 500 credits once, with no card required. Plans start free with 500 credits, then $99 a month for 5,000 credits.

TRY IT

Run the first snippet.

A new account starts with 500 credits and no card. That is enough to find 250 work emails, or 100 people with both a work email and a direct phone.