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
    OverviewHunterSnov.ioProspeoFindymailApollo.ioVoila NorbertSkrapp
Phone finders
Email finders

Migrate from Apollo.io

This guide maps the Apollo.io People Enrichment (POST /api/v1/people/match) and Bulk People Enrichment (POST /api/v1/people/bulk_match) endpoints to Tomba. Apollo.io API behavior checked on 2026-09-30 against the Apollo.io 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.
  • Apollo.io matches a person from whichever identifiers you send. Tomba has one endpoint per input, so pick the endpoint from the identifiers you have: a name and company, a LinkedIn URL, or an email address.
  • Set your HTTP client timeout to at least 180 seconds. Tomba returns the finished result in the response, including phone numbers.

Endpoint mapping

Replace the base URL https://api.apollo.io/api/v1 with https://api.tomba.io/v1. Apollo.io takes POST requests; Tomba lookups are GET requests with query parameters.

Apollo.ioTombaNotes
POST /people/match with a name and domain or organization_nameGET /v1/email-finderReturns the person's work address.
POST /people/match with linkedin_urlGET /v1/linkedinReturns the same fields as the email finder.
POST /people/match with emailGET /v1/people/findReturns the person in the Clearbit-style format; see Enrichment.
POST /people/match with reveal_phone_numberGET /v1/phone-finderOr add enrich_mobile=true to the email finder or LinkedIn finder request.
POST /people/bulk_matchBulk jobsSee Bulk and async jobs.

Authentication changes

Apollo.io reads the key from the x-api-key header, or an OAuth 2.0 bearer token. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret. Tomba also supports OAuth 2.0; see OAuth 2.0.

TerminalCode
# Apollo.io curl -X POST "https://api.apollo.io/api/v1/people/match?first_name=Jane&last_name=Doe&domain=stripe.com" \ -H "x-api-key: $APOLLO_API_KEY" # Tomba curl "https://api.tomba.io/v1/email-finder?first_name=Jane&last_name=Doe&domain=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

Apollo.ioTombaNotes
first_name, last_namefirst_name, last_nameEmail finder.
namefull_nameEmail finder. Used when first_name and last_name aren't both sent.
domaindomainEmail finder. A disposable or webmail domain returns 400 unknown_record.
organization_namecompanyEmail finder. Apollo.io also matches a previous employer; Tomba searches the company you send. A domain gives better results.
linkedin_urlurl on GET /v1/linkedin
emailemail on GET /v1/people/find
reveal_phone_numberenrich_mobile=trueNumbers are returned in data.phone_data in the same response, at an extra cost; no webhook is needed.
webhook_urlwebhook_urlOptional in Tomba. The result is still returned in the response, and also posted to your URL when it qualifies. See Per-request callbacks.
id, hashed_emailNo equivalent
reveal_personal_emailsNo equivalentTomba returns work addresses.
run_waterfall_email, run_waterfall_phoneNo equivalent
poll_onlyNo equivalentEvery Tomba response is final.

Response field mapping

Apollo.io returns the person in person. Tomba's email finder and LinkedIn finder return it in data; the fields are described in Person.

Apollo.ioTombaNotes
person.emaildata.emailnull when no address is found; the status is still 200.
person.email_statusdata.verification.statusSee Status mapping.
person.first_name, last_namedata.first_name, data.last_name
person.namedata.full_name
person.titledata.position
person.linkedin_urldata.linkedin
person.countrydata.countryA two-letter country code in Tomba.
person.departments[]data.departmentOne department. The department names differ.
person.organizationdata.company, data.website_urlThe company name and domain. For a full company profile, call GET /v1/companies/find.
person.phone_numbers[].sanitized_numberdata.phone_data[].e164_formatWith enrich_mobile=true. line_type gives the number type; see Phone response.
person.match_confidencedata.scoreComputed differently. Recalibrate any threshold you apply to it.
person.city, stateNo equivalentGET /v1/people/find returns data.geo.city and data.geo.state when Tomba has them.
person.seniorityNo equivalentGET /v1/people/find returns data.employment.seniority when Tomba has it.
person.id, contact_id, organization_idNo equivalent
person.headline, employment_historyNo equivalent
request_id, waterfallNo equivalentTomba returns a request ID in the X-Request-ID header; see Going to production.

Tomba also returns pattern, type, gender, accept_all, and the sources where the address was found. For the email lookup, GET /v1/people/find returns data.name, data.employment, data.geo, and data.linkedin.handle; see Enrichment.

Status mapping

Apollo.io email_statusTomba verification.status
verifiedvalid

Tomba also returns accept_all, invalid, and unknown, or null when the address hasn't been verified. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

Apollo.io returns an error string. Tomba returns an errors object with type, message, and code:

Apollo.ioTombaWhat to do
400 validation error422 params_invalidFix the parameter named in the message.
400 missing webhook_url with reveal_phone_numberNot returnedTomba doesn't need a webhook for phone numbers.
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.
429 rate limit exceeded429 rate_limitRetry after the Retry-After delay; see Handle 429 responses.

Also handle 402 quota_exceeded when you run out of credits, 400 unknown_record when the email finder receives a disposable or webmail domain, and 451 claimed_email when the owner of an address asked Tomba to stop processing it. GET /v1/people/find returns 200 with an errors object of type not_found when Tomba has no data for the address, so check the body for errors. Error responses don't consume credits; every type is listed in Errors.

Apollo.io reports its limits in x-rate-limit-* and x-*-requests-left headers. Tomba's headers are described in Rate limit headers.

Bulk and async jobs

Apollo.io's bulk endpoint takes up to 10 people in details[] and returns matches[] in the response. Tomba runs lists as bulk jobs; row limits per type are in Bulk types.

Apollo.io details[] entriesTomba bulk type
Name and domain or companyfinder: a CSV file with name and company columns. See Email finder.
linkedin_urllinkedin: a JSON list of profile URLs or a CSV file. See LinkedIn finder.
emailenrich: a JSON list of addresses or a CSV file. See Email enrichment.
reveal_phone_numberSet phone to true on the job, at an extra cost.

Each job is created, launched, polled, and downloaded as CSV; see Lifecycle. To be notified when a job ends, set webhook_url; see Bulk job events. A job is charged when you first download its results; see Billing.

The bulk response fields total_requested_enrichments, unique_enriched_records, missing_records, and credits_consumed have no equivalent. Poll the job's progress instead.

Code example

This function replaces a people/match call made with a name and company or with a LinkedIn URL. It returns Apollo.io's person field names, or null when Tomba finds no address. 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, }; // Accepts Apollo.io's parameters: linkedin_url, or first_name + last_name // (or name) with domain or organization_name. async function peopleMatch(params) { let url; if (params.linkedin_url) { url = new URL("https://api.tomba.io/v1/linkedin"); url.searchParams.set("url", params.linkedin_url); } else { url = new URL("https://api.tomba.io/v1/email-finder"); const map = { first_name: "first_name", last_name: "last_name", name: "full_name", domain: "domain", organization_name: "company", }; for (const [apollo, tomba] of Object.entries(map)) { if (params[apollo]) url.searchParams.set(tomba, params[apollo]); } } if (params.reveal_phone_number) url.searchParams.set("enrich_mobile", "true"); 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 found = body.data; if (!found.email) return null; const status = found.verification?.status?.toLowerCase() ?? null; return { first_name: found.first_name, last_name: found.last_name, name: found.full_name, email: found.email, // Apollo.io's "verified" is Tomba's "valid"; other statuses pass through. email_status: status === "valid" ? "verified" : status, title: found.position, linkedin_url: found.linkedin, country: found.country, phone_numbers: (found.phone_data ?? []).map((phone) => ({ sanitized_number: phone.e164_format, })), }; } console.log( await peopleMatch({ first_name: "Jane", last_name: "Doe", domain: "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 x-api-key.
  2. Route each people/match call by its input: a name and company to /v1/email-finder, a LinkedIn URL to /v1/linkedin, and an email address to /v1/people/find.
  3. Replace reveal_phone_number and its webhook with enrich_mobile=true, and read the numbers from data.phone_data.
  4. Update response parsing: read data instead of person, position instead of title, linkedin instead of linkedin_url, and translate email_status with the status mapping.
  5. Handle 402 for exhausted credits, retry 429 after Retry-After, and drop addresses that return 451.
  6. Move bulk_match batches to finder, linkedin, or enrich 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
FindymailVoila Norbert
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