Copy page

Clearbit

Migrate from the Clearbit Person API

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

# Tomba
curl "https://api.tomba.io/v1/people/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

Tomba returns the person in data and the address you looked up in meta.email. 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.gender and data.verification.

Status mapping

Clearbit's Person API has no deliverability status. Tomba adds data.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 person 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.

To enrich a list of addresses, run a bulk job of type enrich with a newline-separated list:

Code
curl -X POST "https://api.tomba.io/v1/bulk/enrich" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sign-ups", "list": "jane.doe@stripe.com\njohn.smith@shopify.com"}'

Launch the job, poll its progress, and download the results as CSV, as shown in Lifecycle. The CSV has Tomba's email enrichment columns, not Clearbit's JSON shape. A job is charged when you first download its results; see Billing.

Code example

This function replaces a Person API lookup. It returns the Clearbit-style person object, or null when Tomba has no record. 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 findPerson(email) {
    const url = new URL("https://api.tomba.io/v1/people/find");
    url.searchParams.set("email", email);
    const res = await fetch(url, { headers: TOMBA_HEADERS });
    const body = await res.json();
    if (body.errors) {
        // Unknown people and disposable or webmail addresses 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}`,
        );
    }
    return body.data;
}

const person = await findPerson("jane.doe@stripe.com");
if (person) {
    console.log(
        person.name.fullName,
        person.employment.title,
        person.employment.name,
    );
    console.log(
        "Verification status:",
        person.verification?.status ?? "not verified",
    );
}

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/people/find with the email address only, and read the person from data.
3. Treat a 200 response with an errors object as not found, and remove 202 retries.
4. Update code that depends on fields Tomba formats differently (location, employment.role, linkedin.handle, twitter.handle, phone) or leaves null.
5. Handle 402, retry 429 after Retry-After, and remove addresses that return 451.
6. Look up the same sample of addresses with both services and compare the fields you use before you switch production traffic.