Copy page

SDKs

Node.js SDK

tomba is the official Node.js client for the Tomba API. Each API area is a service class, and each method returns a promise for one request.

Requirements

• Node.js. package.json declares no minimum version; the SDK is built and tested on Node.js 20.
• axios, installed as a dependency.

Install

Code
npm install tomba

The package is CommonJS with TypeScript declarations. The examples on this page are ES modules: save them as .mjs files, or set "type": "module" in your package.json.

Authenticate

Create an API key and copy your secret on the API keys page, then export both:

Code
export TOMBA_API_KEY="ta_xxxx"
export TOMBA_SECRET_KEY="ts_xxxx"

The SDK doesn't read environment variables. Pass the values to setKey() and setSecret(), and the client sends them as the X-Tomba-Key and X-Tomba-Secret headers. Key expiry and rotation are covered in Authentication.

First request

Find the email address of a person at a company:

Code
import { TombaClient, Finder } from "tomba";

const client = new TombaClient()
    .setKey(process.env.TOMBA_API_KEY)
    .setSecret(process.env.TOMBA_SECRET_KEY);

const result = await new Finder(client).emailFinder({
    domain: "stripe.com",
    firstName: "Jane",
    lastName: "Doe",
});
console.log(result.data.data.email);

Every method resolves to { data, rateLimit }, where data is the decoded JSON body. The API wraps its payload in its own data object (Response format), so the address is at result.data.data.email. The TypeScript declarations type result.data as the payload itself, so TypeScript code needs a cast to read result.data.data.

Errors

Methods reject with TombaException, a subclass of Error, when the API responds with status 400 or higher, and before sending a request when a required argument is missing.

Code
import { TombaClient, Finder, TombaException } from "tomba";

const client = new TombaClient()
    .setKey(process.env.TOMBA_API_KEY)
    .setSecret(process.env.TOMBA_SECRET_KEY);

try {
    const result = await new Finder(client).emailFinder({
        domain: "stripe.com",
        firstName: "Jane",
        lastName: "Doe",
    });
    console.log(result.data.data.email);
} catch (error) {
    if (!(error instanceof TombaException)) throw error;
    console.log(
        error.code?.status,
        error.message,
        error.response?.errors?.type,
    );
}

Enrichment.person(), company(), and combined() don't reject when nothing is found: those endpoints answer with status 200 and an errors body, so check result.data.errors. Each errors.type is described in Errors.

Rate limits and retries

The SDK doesn't retry. result.rateLimit holds the response's rate limit headers as secondLimit, minuteLimit, dailyLimit, minuteRemaining, dailyRemaining, minuteReset, dailyReset, retryAfter, policy, and rateLimit. Numeric headers are parsed as integers, and a header that is absent or 0 becomes null.

A 429 rejects with TombaException; read the wait time from error.code.headers["retry-after"] and retry as described in Handle 429 responses.

Requests time out after 120 seconds. Change the timeout with client.setTimeout(milliseconds).

Method reference

Create each service with the client, for example new Finder(client). Every class is a named export of tomba.

type is the {type} segment listed in Bulk types; the order of calls is described in Lifecycle. Bulk.create() sends a JSON body, so it can't create jobs that need a CSV upload, such as email finder jobs. Bulk.download() returns the results file, a CSV, as a string in result.data.

Source

github.com/tomba-io/node (Apache-2.0). Release notes are in CHANGELOG.md.