Copy page

Clearbit

Migrate from the Clearbit Combined API

This guide maps Clearbit's Combined API (GET https://person.clearbit.com/v2/combined/find) to Tomba's GET /v1/combined/find, which returns a Clearbit-style person and company for an email address. 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://person.clearbit.com/v2/combined/find?email=jane.doe@stripe.com" \
  -H "Authorization: Bearer $CLEARBIT_API_KEY"

# Tomba
curl "https://api.tomba.io/v1/combined/find?email=jane.doe@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

Inside data.person and data.company, fields map as described in the Person and Company guides:

• Person API response fields
• Company API response fields

Status mapping

Clearbit's Combined API has no deliverability status. Tomba adds data.person.verification, with the date and status of the address's last verification. The status uses the verifier's values, described in Status values, and is null when the address hasn't been verified. Compare it case-insensitively.

Error mapping

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

Bulk and async jobs

Tomba answers every combined lookup synchronously, so remove 202 retries. A webhook_url callback carries the same JSON as the response, without Clearbit's id, type, and status wrapper, and isn't signed.

There is no combined bulk type. For a list, run an enrich job for the addresses and a company job for their domains; see Email enrichment and Company enrichment. Each job is created, launched, polled, and downloaded as CSV; see Lifecycle.

Code example

This function replaces a Combined API lookup and returns Clearbit's {person, company} shape, with company set to null when Tomba has no company. 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 findCombined(email) {
    const url = new URL("https://api.tomba.io/v1/combined/find");
    url.searchParams.set("email", email);
    const res = await fetch(url, { headers: TOMBA_HEADERS });
    const body = await res.json();
    if (body.errors) {
        // No person found, or a disposable or webmail address: HTTP 200 with an errors object.
        if (res.ok) return { person: null, company: null };
        throw new Error(
            `${res.status} ${body.errors.type}: ${body.errors.message}`,
        );
    }
    const { person, company } = body.data;
    // Tomba returns an object with null fields when it has no company.
    return { person, company: company.domain ? company : null };
}

const { person, company } = await findCombined("jane.doe@stripe.com");
console.log(person?.name.fullName, company?.name ?? "no company");

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/combined/find with the email address only, and read data.person and data.company.
3. Treat a 200 response with an errors object as not found, and check data.company.domain instead of testing company for null.
4. Where you relied on company-only results, add a fallback call to /v1/companies/find.
5. Apply the person and company field changes from the Person and Company guides, and remove 202 retries.
6. Handle 402, retry 429 after Retry-After, and remove addresses that return 451.
7. Look up the same sample of addresses with both services and compare the fields you use before you switch production traffic.