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

> 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.

Source page: https://descovo.com/docs/node
Updated: November 20, 2026

## 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:

```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:

```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:

```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:

```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

| 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 |

errors.ts:

```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.

## Next

- [Get an API key](https://descovo.com/sign-up)
- [REST reference](https://descovo.com/docs/rest)
- [Python guide](https://descovo.com/docs/python)
- [REST API reference: every route](https://descovo.com/docs/rest)
- [Contact enrichment API overview](https://descovo.com/contact-enrichment-api)
