Copy page

Clearbit

Migrate from the Clearbit Company API

This guide maps Clearbit's Company API (GET https://company.clearbit.com/v2/companies/find) to Tomba's GET /v1/companies/find, which returns a Clearbit-style company object. Clearbit behavior checked on 2026-09-29 against the last public Clearbit API reference (September 2024).

Before you begin

• Get your API key (ta_…) and secret (ts_…); see Authentication.
• Check what a lookup costs in Credit costs and your plan's throttling in Limits by plan.
• Read Migrate from Clearbit for the changes shared by every Clearbit endpoint.

Endpoint mapping

Authentication changes

Clearbit takes the key as the basic auth username or as a bearer token. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

Code
# Clearbit
curl "https://company.clearbit.com/v2/companies/find?domain=stripe.com" \
  -u "$CLEARBIT_API_KEY:"

# Tomba
curl "https://api.tomba.io/v1/companies/find?domain=stripe.com" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY"

Tomba API keys expire; plan their rotation with Key expiry.

Parameter mapping

Response field mapping

Tomba returns the company in data and the domain you looked up in meta.domain. Every field in Clearbit's reference is listed below; "Always null" means Tomba returns the key but never fills it. Field definitions are in Enrichment.

Tomba also returns data.whois, with the domain's registrar_name, created_date, and referral_url.

Error mapping

Error responses don't consume credits. Every type is listed in Errors.

Bulk and async jobs

Tomba answers every company lookup synchronously and sends no callback for it, so remove 202 retries and webhook handlers. To enrich a list of domains, run a bulk job of type company with a newline-separated list:

Code
curl -X POST "https://api.tomba.io/v1/bulk/company" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Target accounts", "list": "stripe.com\nshopify.com"}'

Launch the job, poll its progress, and download the results as CSV, as shown in Lifecycle. The CSV doesn't follow Clearbit's JSON shape. A job is charged when you first download its results; see Billing.

Code example

This function replaces a Company API lookup. It returns the Clearbit-style company object, or null when Tomba has no record, and fills logo with Tomba's logo URL. It needs Node.js 18 or later.

Code
const TOMBA_HEADERS = {
    "X-Tomba-Key": process.env.TOMBA_API_KEY,
    "X-Tomba-Secret": process.env.TOMBA_SECRET_KEY,
};

async function findCompany(domain) {
    const url = new URL("https://api.tomba.io/v1/companies/find");
    url.searchParams.set("domain", domain);
    const res = await fetch(url, { headers: TOMBA_HEADERS });
    const body = await res.json();
    if (body.errors) {
        // Unknown, disposable, and webmail domains come back as HTTP 200 with an errors object.
        if (res.ok) return null;
        throw new Error(
            `${res.status} ${body.errors.type}: ${body.errors.message}`,
        );
    }
    const company = body.data;
    company.logo = `https://logo.tomba.io/${company.domain}`;
    return company;
}

const company = await findCompany("stripe.com");
console.log(company?.name, company?.metrics.employees, company?.logo);

Cutover checklist

1. Store the Tomba key and secret as TOMBA_API_KEY and TOMBA_SECRET_KEY, and send them as X-Tomba-Key and X-Tomba-Secret instead of basic auth or a bearer token.
2. Call https://api.tomba.io/v1/companies/find and read the company from data.
3. Treat a 200 response with an errors object as not found, and remove 202 retries and webhook handling.
4. Update code that depends on fields Tomba formats differently (foundedYear, location, emailProvider, type, metrics, linkedin.handle) or leaves null, and build logo URLs on logo.tomba.io.
5. Handle 402, and retry 429 after Retry-After.
6. Look up the same sample of domains with both services and compare the fields you use before you switch production traffic.