TombaTomba
Start free
  • Documentation
  • API reference
  • SDKs & CLI
  • AI & MCP
  • Integrations
  • Enterprise
  • Migration guides

Find, verify and enrich B2B contacts from public sources, in the app, your spreadsheet or through the API.

GDPR & CCPA

// docs

  • API changelog
  • Support options
  • Security

// platform

  • Dashboard
  • Pricing
  • API status

// resources

  • Help center
  • Product updates
  • TombaBot crawler

// company

  • Website
  • Contact us
  • Edit or remove your data

© 2021–2026 Tomba.io

  • Terms of service
  • Privacy policy
  • Cookie policy
  • Security policy
  • GDPR
  • CCPA
Clearbit
    OverviewCompany APIPerson APICombined API
Email verifiers
Email finders
Phone finders
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

ClearbitTomba
GET https://person.clearbit.com/v2/combined/find?email=GET https://api.tomba.io/v1/combined/find?email=
GET https://person-stream.clearbit.com/v2/combined/find?email=GET https://api.tomba.io/v1/combined/find?email=

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:

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

ClearbitTombaNotes
emailemailRequired.
webhook_urlwebhook_urlTomba still returns the result in the response, and also posts a copy when a person is found. See Per-request callbacks.
webhook_idNo equivalent
given_name, family_name, ip_address, location, company, company_domain, linkedin, twitter, facebookNo equivalentTomba matches on the email address only.
subscribe, suppressionNo equivalent
API-Version headerNo equivalent

Response field mapping

ClearbitTombaNotes
persondata.personAlways an object. When Tomba has no person for the address, the whole response is not_found; see Error mapping.
companydata.companyWhen Tomba has no company for the person's domain, an object whose fields are all null, not null itself. Check data.company.domain.
No equivalentmeta.emailThe address you looked up. An empty string when no company was found.

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

ClearbitTombaWhat to do
202 lookup queuedNot returnedRemove the retry-on-202 logic.
200 with only company200 with an errors object: type not_found, code 404Tomba needs the person. To still get the company, call GET /v1/companies/find with the address's domain.
404 neither found200 with an errors object: type not_found, code 404Check the body for errors, not only the status.
422 validation error422 params_invalid for a malformed address. A disposable or webmail address returns 200 with an errors object: type params_invalid, code 422.Send a work address.
401 invalid API key400 authentication_failed (missing or malformed), 400 api_key_expired, 401 authentication_failed (wrong key or secret)Check both headers; rotate an expired key.
402 over quota402 quota_exceededWait for your usage window to renew or add credits.
429 rate limit429 rate_limitRetry after the Retry-After delay; see Handle 429 responses.
No equivalent451 claimed_emailThe owner of the address asked Tomba to stop processing it. Remove it from your data.
50X500 api_errorRetry with backoff.

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.
Last modified on September 30, 2026
Person APIOverview
On this page
  • Before you begin
  • Endpoint mapping
  • Authentication changes
  • Parameter mapping
  • Response field mapping
  • Status mapping
  • Error mapping
  • Bulk and async jobs
  • Code example
  • Cutover checklist
Javascript