// 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.
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.
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.
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.
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
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_request | The body does not match the route, for example an unknown field. Fix it; nothing was charged |
| 401 | unauthorized | No key, or a revoked key |
| 402 | insufficient_credits | Out of credits. Stop and top up; retrying will not help |
| 429 | rate_limited | Too fast. Wait and retry |
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.