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 RocketReach

This guide maps RocketReach's People Lookup, People Lookup Status, Bulk People Lookup, and Account endpoints to Tomba; the Universal API endpoints (/universal/*) aren't covered. RocketReach API behavior checked on 2026-09-30 against the RocketReach API reference.

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.rocketreach.co/api/v2 with https://api.tomba.io/v1. RocketReach's person lookup takes any identifier; Tomba has one endpoint per identifier:

RocketReachTombaNotes
GET /person/lookup with linkedin_urlGET /v1/linkedin with enrich_mobile=trueReturns the email address and the person's numbers in data.phone_data.
GET /person/lookup with linkedin_url, phones onlyGET /v1/phone-finder with linkedinSet full=true to get every number.
GET /person/lookup with name, current_employerGET /v1/email-finder with enrich_mobile=trueReturns the email address and the person's numbers in data.phone_data.
GET /person/lookup with emailGET /v1/enrich with enrich_mobile=true, or GET /v1/phone-finder with emailEmail Enrichment returns the person; Phone Finder returns only numbers.
GET /person/lookup with phoneNo equivalentTomba doesn't look up a person from a number. GET /v1/phone-validator checks the number itself.
GET /person/lookup with id or npi_numberNo equivalentStore the LinkedIn URL, email address, or name and company instead.
GET /person/checkStatusNo equivalentTomba returns the final result in the lookup response. Remove the polling.
POST /bulkLookupBulk jobsSee Bulk and async jobs.
GET /account/GET /v1/meSee Check usage.

Authentication changes

RocketReach takes the key in the Api-Key header, or in the deprecated api_key query parameter. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and doesn't accept credentials in the query string:

TerminalCode
# RocketReach curl "https://api.rocketreach.co/api/v2/person/lookup?linkedin_url=https://www.linkedin.com/in/jane-doe" \ -H "Api-Key: $ROCKETREACH_API_KEY" # Tomba curl "https://api.tomba.io/v1/linkedin?url=https://www.linkedin.com/in/jane-doe&enrich_mobile=true" \ -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

RocketReachTombaNotes
linkedin_url, linkedin_ext_urlurl on LinkedIn Finder, linkedin on Phone FinderSend a full profile URL, such as https://www.linkedin.com/in/jane-doe.
namefull_name on Email FinderOr send first_name and last_name.
current_employercompany on Email FinderSend domain instead when you have the company's domain.
emailemail on Email Enrichment or Phone Finder
titleNo equivalentThe response carries position; compare it in your code.
phone, id, npi_numberNo equivalent
lookup_typeenrich_mobile, or the choice of endpointSet enrich_mobile=true on Email Finder, LinkedIn Finder, or Email Enrichment to get numbers, at an extra cost; see Credit costs.
return_cached_emailsNo equivalentTomba doesn't return partial results.
webhook_idwebhook_urlPass the callback URL on each request instead of an ID registered in the dashboard; see Webhooks.
metadataNo equivalentKeep your own IDs and tags alongside the request.

Response field mapping

RocketReach returns the profile at the top level. Tomba returns the person under data, and phone numbers under data.phone_data[] on the finders or data on Phone Finder.

Person and email fields

RocketReachTombaNotes
namedata.full_nameAlso first_name and last_name.
current_titledata.position
current_employerdata.company
current_employer_domaindata.website_url
linkedin_urldata.linkedin
country_codedata.countryTomba uses ISO 3166-1 alpha-2 codes.
recommended_email, recommended_professional_email, current_work_emaildata.emailnull when no address is found; the status is still 200.
emails[].emaildata.emailTomba returns one address. LinkedIn Finder returns up to two with full=true, without phone_data.
emails[].smtp_validdata.verification.statusSee Status mapping.
emails[].last_validation_checkdata.verification.date
emails[].type role-baseddata.type genericTomba's personal means an address that belongs to one person, not a personal mailbox.
emails[].gradedata.scoreA 0 to 100 confidence, computed differently. Recalibrate any threshold you apply to it.
recommended_personal_email, current_personal_emailNo equivalent
current_employer_website, current_employer_linkedin_url, current_employer_industryGET /v1/companies/findCall it with data.website_url.
city, region, location, region_latitude, region_longitudeNo equivalent
job_history, education, skills, birth_year, npi_data, connections, links, tags, profile_list, metadataNo equivalent
id, statusNo equivalentTomba has no lookup IDs or lookup states.

Tomba also returns department, gender, twitter, accept_all, and sources; see Person response.

Phone fields

RocketReachTombaNotes
phones[].numberintl_formatTomba also returns local_format and rfc3966_format.
phones[].e164e164_format
phones[].country_codeNo equivalentRocketReach returns the calling code, such as 1. Tomba's country_code is the ISO 3166-1 alpha-2 country, such as US.
phones[].typeline_typeSee Status mapping.
phones[].grade, validityvalidvalid only says whether the number fits its country's numbering plan; there's no identity-match grade.
phones[].recommendedPhone Finder without fullThe single number Phone Finder returns prefers a valid one.
phones[].extensionNo equivalent
No equivalentcarrier, region, timezonesSee Phone response.

On the finders, data.phone_number is true when Tomba has a number for the person; data.phone_data is filled only with enrich_mobile=true. When Phone Finder finds nothing, the status is 200 and data is an empty array.

Status mapping

RocketReach's lookup status (complete, failed, waiting, searching, progress) has no equivalent: every Tomba response is final. Email and phone statuses map as follows:

RocketReach emails[].smtp_validTomba data.verification.status
validvalid
invalidinvalid
accept-allaccept_all
unknownunknown

Tomba can also return disposable, or null when the address hasn't been verified. Compare status case-insensitively. Each value is defined in Status values.

RocketReach phones[].typeTomba line_type
mobileMOBILE
direct dial, otherNo direct equivalent. Tomba reports the line itself: FIXED_LINE, VOIP, TOLL_FREE, and others.

Every value is listed in Line types.

Error mapping

RocketReach returns an error body with detail or message. Tomba returns an errors object with type, message, and code:

RocketReachTombaWhat to do
400 malformed or missing parameters422 params_invalidFix the parameter named in the message.
401 missing or 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.
403 out of lookup credits402 quota_exceededWait for your usage window to renew or add credits.
403 key lacks permission403Your plan doesn't include the feature; see Errors.
404 profile doesn't exist200 with data.email null, or an empty data array on Phone FinderCheck the body, not the status.
429 with Retry-After429 rate_limit with Retry-AfterRetry after the delay; see Handle 429 responses.
500500 api_errorRetry with backoff.

Also handle 451 claimed_email or 451 claimed_linkedin when the person asked Tomba to stop processing their data. Error responses don't consume credits; every type is listed in Errors. RocketReach's RR-Request-ID header corresponds to Tomba's request ID; see Request IDs.

Bulk and async jobs

RocketReach's POST /bulkLookup takes 1 to 100 queries and delivers results to a webhook. Tomba runs lists as bulk jobs, which can send an event to a webhook_url when they end:

RocketReach queryTomba bulk type
linkedin_url, for phonesphone-finder: a JSON list of LinkedIn URLs, or a CSV file with a linkedin column. See Phone finder.
email, for phonesphone-finder: a JSON list of email addresses, or a CSV file with an email column. See Phone finder.
linkedin_url, for emailslinkedin: a JSON list of profile URLs. See LinkedIn finder.
name and current_employerfinder: a CSV file with name and company columns. See Email finder.

Each job is created, launched, polled, and downloaded as CSV; see Lifecycle. A job is charged when you first download its results; see Billing. Limits are in Limits.

Code example

This function replaces a call to RocketReach's GET /person/lookup and returns RocketReach's field names, or null when no person is found. 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, }; const SMTP_VALID = { valid: "valid", invalid: "invalid", accept_all: "accept-all", unknown: "unknown", }; // Accepts RocketReach's linkedin_url, email, or name + current_employer. async function personLookup(params) { let path; const query = { enrich_mobile: "true" }; if (params.linkedin_url) { path = "linkedin"; query.url = params.linkedin_url; } else if (params.email) { path = "enrich"; query.email = params.email; } else if (params.name && params.current_employer) { path = "email-finder"; query.full_name = params.name; query.company = params.current_employer; } else { throw new Error( "Send linkedin_url, email, or name and current_employer", ); } const url = new URL(`https://api.tomba.io/v1/${path}`); for (const [key, value] of Object.entries(query)) { 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}`, ); } const person = body.data; const phones = person.phone_data ?? []; if (!person.email && phones.length === 0) return null; const status = person.verification?.status?.toLowerCase(); return { status: "complete", name: person.full_name, current_title: person.position, current_employer: person.company, current_employer_domain: person.website_url, linkedin_url: person.linkedin, country_code: person.country, recommended_professional_email: person.email, emails: person.email ? [ { email: person.email, smtp_valid: SMTP_VALID[status] ?? null, type: person.type === "generic" ? "role-based" : "professional", last_validation_check: person.verification?.date ?? null, }, ] : [], phones: phones.map((phone) => ({ number: phone.intl_format, e164: phone.e164_format, type: phone.line_type === "MOBILE" ? "mobile" : "other", })), }; } console.log( await personLookup({ linkedin_url: "https://www.linkedin.com/in/jane-doe", }), );

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 identifier: LinkedIn URLs to /v1/linkedin, names and companies to /v1/email-finder, email addresses to /v1/enrich, and phone-only lookups to /v1/phone-finder. Add enrich_mobile=true where you need numbers.
  3. Remove the /person/checkStatus polling and the lookup webhook handler, or pass webhook_url per request.
  4. Update response parsing: read fields under data, numbers from data.phone_data, and treat data.email null or an empty data array as not found instead of 404.
  5. Swap error handling: 402 replaces RocketReach's out-of-credits 403, 422 replaces 400, and errors is an object.
  6. Move /bulkLookup batches to phone-finder, linkedin, and finder bulk jobs.
  7. Run the same sample of people through both services and compare the results before you switch production traffic.
Last modified on September 30, 2026
Kaspr
On this page
  • Before you begin
  • Endpoint mapping
  • Authentication changes
  • Parameter mapping
  • Response field mapping
    • Person and email fields
    • Phone fields
  • Status mapping
  • Error mapping
  • Bulk and async jobs
  • Code example
  • Cutover checklist
Javascript