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
Email verifiers
Email finders
Phone finders
    OverviewLushaContactOutKasprRocketReach
Phone finders

Migrate from Lusha

This guide maps the phone lookups of Lusha's Person API (GET /v2/person, POST /v2/person) and the v3 Search and Enrich Contacts endpoints to Tomba. Lusha API behavior checked on 2026-09-30 against the Lusha API reference and Lusha API error codes.

Before you begin

  • Get your API key (ta_…) and secret (ts_…); see Authentication.
  • Check what each endpoint costs in Credit costs and your plan's throttling in Limits by plan.
  • Set your HTTP client timeout to at least 180 seconds. Tomba returns the finished result in the response.

Endpoint mapping

Replace the base URL https://api.lusha.com with https://api.tomba.io. Tomba picks the endpoint by the identifier you have:

LushaTombaNotes
GET /v2/person with email or linkedinUrlGET /v1/phone-finderReturns phone numbers only.
GET /v2/person with firstName, lastName, and a companyGET /v1/email-finder with enrich_mobile=trueNumbers are in data.phone_data, next to the email address.
GET /v2/person with personIdNo equivalentLook the person up by email address, LinkedIn URL, or name and company.
POST /v2/personSingle requests, or a bulk job
POST /v3/contacts/search-and-enrichSingle requests, or a bulk jobMap each entry in contacts as a GET /v2/person call.
POST /v3/contacts/search, then POST /v3/contacts/enrichOne request per personTomba has no separate reveal step: the lookup returns the numbers.
No equivalentGET /v1/phone-validatorChecks a number you already have and returns its line type, carrier, and region.

Authentication changes

Lusha reads the key from the api_key header. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

TerminalCode
# Lusha curl -G "https://api.lusha.com/v2/person" \ --data-urlencode "email=jane.doe@stripe.com" \ -H "api_key: $LUSHA_API_KEY" # Tomba curl -G "https://api.tomba.io/v1/phone-finder" \ --data-urlencode "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

LushaTombaNotes
emailemailOn /v1/phone-finder.
linkedinUrllinkedinOn /v1/phone-finder. Send the full profile URL, such as https://www.linkedin.com/in/jane-doe.
firstName, lastNamefirst_name, last_nameOn /v1/email-finder with enrich_mobile=true. /v1/email-finder also accepts full_name.
companyDomaindomainOn /v1/email-finder. On /v1/phone-finder, domain returns the company's number, not the person's.
companyNamecompanyOn /v1/email-finder.
revealPhonesNot needed/v1/phone-finder returns only phone numbers. On the finder endpoints, enrich_mobile=true adds them.
filterBy=phoneNumbersNot neededA phone finder request with no number returns an empty data array.
No equivalentfullfull=true returns every number found as an array; without it, data holds one number, preferring a valid one.
personId, refreshJobInfo, partialProfile, revealEmails, signals, signalsStartDateNo equivalent

Response field mapping

Lusha returns the person in contact.data. The Tomba phone finder returns the number itself in data, or an array of numbers with full=true:

LushaTombaNotes
contact.data.phoneNumbers[].number, v3 phones[].numberdata.e164_formatAlso in intl_format, local_format, and rfc3966_format.
contact.data.phones (deprecated)data.e164_format
contact.data.phoneNumbers[].phoneType, v3 phones[].typedata.line_typeDifferent values; see Status mapping.
contact.data.phoneNumbers[].doNotCall, v3 phones[].doNotCallNo equivalentCheck Do Not Call registries yourself before you dial.
contact.data.phoneNumbers[].updateDateNo equivalent
contact.isCreditChargedNo equivalentWhen a request is charged is listed in Credit costs.
contact.data.location.countryIso2No equivalent on the phone finderdata.country_code is the country of the number, not of the person.
Name, job title, company, and social fields in contact.dataNo equivalent on the phone finder/v1/email-finder returns the name, position, company, and LinkedIn URL. For a full profile, see the Person API.
Email fields in contact.dataNo equivalent on the phone finderUse /v1/email-finder or GET /v1/linkedin.

Tomba also returns valid, carrier, region, and timezones for each number, and the email, domain, or linkedin it was found for. Every field is described in Phone response.

Status mapping

LushaTomba
phoneType Mobile, v3 type mobileline_type MOBILE
phoneType Direct or Phone, v3 direct or workNo direct equivalent. Tomba reports the kind of line, such as FIXED_LINE, VOIP, or FIXED_LINE_OR_MOBILE.
contact.error.name EMPTY_DATA, or 404200 with data as an empty array
No equivalentvalid is false: the number isn't valid in its country's numbering plan

Every line_type value is defined in Line types. With full=true, filter on valid if you only want valid numbers.

Error mapping

Lusha returns errors as {statusCode, message, errors}. Tomba returns an errors object with type, message, and code:

LushaTombaWhat to do
400 validation failed, 412 invalid syntax422 params_invalidFix the parameter named in the message. Sending none of email, domain, and linkedin to /v1/phone-finder also returns 422.
401 missing or invalid 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 insufficient credits402 quota_exceededWait for your usage window to renew or add credits.
403 account inactive401 authentication_failedContact support.
404 record not in the database200 with data as an empty arrayTreat as no match.
429 rate limit or daily quota429 rate_limitRetry after the Retry-After delay; see Handle 429 responses.
451 GDPR restriction451 claimed_email or 451 claimed_linkedinThe person asked Tomba to stop processing their data. Remove the record from your data.
499 client closed request504 after 180 secondsRaise your client timeout, or use a bulk job.
500500 api_errorRetry with backoff.

Error responses don't consume credits. Every type is listed in Errors, and Tomba's rate limit headers are in Rate limit headers.

Bulk and async jobs

Lusha's POST /v2/person and v3 contact endpoints answer up to 100 contacts in one synchronous response, keyed by your contactId or clientReferenceId. A Tomba bulk job runs in the background: create it, launch it, poll its progress, and download the results as CSV. For a few contacts, send single requests instead.

Lusha inputTomba bulk type
Contacts with email or linkedinUrlphone-finder: a JSON list or CSV file of email addresses or LinkedIn URLs. See Phone finder.
Contacts with a name and companyfinder with find_phones set to true: a CSV file with name and company columns. See Email finder.

A JSON list is de-duplicated and reordered, so join the results back to your records on the email address or LinkedIn URL, not on position. The requests for each step are in Lifecycle, and webhook_url sends an event when a job ends; see Bulk job events. A job is charged when you first download its results; see Billing.

Code example

This function replaces a GET /v2/person phone lookup and returns Lusha's phoneNumbers shape, or null when no number is found. It sends an email address or LinkedIn URL to the phone finder, and a name and company to the email finder with enrich_mobile=true. 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 tombaGet(path, params) { const url = new URL(path, "https://api.tomba.io"); for (const [key, value] of Object.entries(params)) { if (value) url.searchParams.set(key, value); } const res = await fetch(url, { headers: TOMBA_HEADERS }); const body = await res.json(); if (body.errors) { throw new Error( `${res.status} ${body.errors.type}: ${body.errors.message}`, ); } return body.data; } // Accepts Lusha's parameters: email, linkedinUrl, or firstName + lastName // with companyDomain or companyName. async function findPhones(params) { let numbers; if (params.email || params.linkedinUrl) { numbers = await tombaGet("/v1/phone-finder", { email: params.email, linkedin: params.linkedinUrl, full: "true", }); } else { const person = await tombaGet("/v1/email-finder", { first_name: params.firstName, last_name: params.lastName, domain: params.companyDomain, company: params.companyName, enrich_mobile: "true", }); numbers = person.phone_data ?? []; } if (numbers.length === 0) return null; return { phoneNumbers: numbers.map((phone) => ({ number: phone.e164_format, lineType: phone.line_type, valid: phone.valid, })), }; } console.log(await findPhones({ email: "jane.doe@stripe.com" }));

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 api_key.
  2. Route each lookup by its identifier: email address or LinkedIn URL to /v1/phone-finder, name and company to /v1/email-finder with enrich_mobile=true. Replace personId lookups with one of these.
  3. Read numbers from data (with full=true) or data.phone_data instead of contact.data.phoneNumbers, and map phoneType to line_type.
  4. Treat an empty data array as no match, in place of EMPTY_DATA and 404.
  5. Swap error handling: 422 replaces 400 and 412, 451 carries a claimed_* type, and errors is an object.
  6. Move batches of up to 100 contacts to Tomba bulk jobs, or loop over single requests.
  7. Run the same sample of contacts through both services and compare the numbers before you switch production traffic.
Last modified on November 6, 2026
OverviewContactOut
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