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 Findymail

This guide maps the Findymail API (the /api/search/* endpoints, /api/verify, and /api/credits) to Tomba. Findymail API behavior checked on 2026-09-29 against the Findymail 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.
  • Findymail endpoints take POST requests with JSON bodies. Tomba lookups are GET requests with query parameters.

Endpoint mapping

Replace the host app.findymail.com with api.tomba.io.

FindymailTombaNotes
POST /api/search/nameGET /v1/email-finder
POST /api/search/domainGET /v1/domain-search
POST /api/search/employeesGET /v1/domain-searchReturns people with their addresses. Filters by department, not job title.
POST /api/search/business-profileGET /v1/linkedin
POST /api/search/reverse-emailGET /v1/enrichReturns the person, company, and LinkedIn URL for an address.
POST /api/search/phoneGET /v1/phone-finderAlso accepts an email address or a domain.
POST /api/search/companyGET /v1/companies/findLooks up by domain only.
POST /api/verifyGET /v1/email-verifier
GET /api/creditsGET /v1/me

Authentication changes

Findymail reads a bearer token. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

TerminalCode
# Findymail curl -X POST "https://app.findymail.com/api/search/name" \ -H "Authorization: Bearer $FINDYMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Jane Doe", "domain": "stripe.com"}' # Tomba curl -G "https://api.tomba.io/v1/email-finder" \ --data-urlencode "full_name=Jane Doe" \ --data-urlencode "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

Findymail endpoint and fieldTomba parameterNotes
search/name namefull_nameOr send first_name and last_name.
search/name domaindomain or companyFindymail takes a domain or a company name in one field. Send a domain as domain and a company name as company.
webhook_urlwebhook_urlTomba still returns the result in the response, and also posts it to your URL when the result qualifies. See Per-request callbacks.
search/domain domain, search/employees websitedomain
search/domain roles, search/employees job_titlesdepartmentTomba filters by department from a fixed list, not by free-text role. The values are in the API reference.
search/employees countlimitThe cost depends on limit; see Credit costs.
search/business-profile linkedin_urlurl
search/reverse-email emailemail
search/reverse-email with_profileNo equivalent/v1/enrich returns every person field it has.
search/phone linkedin_urllinkedin
search/company domaindomain
search/company linkedin_url, nameNo equivalentGet the domain for a company name with GET /v1/domain-suggestions.
verify emailemail

Response field mapping

Tomba wraps every result in data.

FindymailTombaNotes
contact.emaildata.emailnull when no address is found.
contact.namedata.full_namedata.first_name and data.last_name are also returned.
contact.domaindata.website_url
contacts[] (search/domain)data.emails[]Each item has email, full_name, position, department, and verification.
Employees name, jobTitle, linkedinUrldata.emails[].full_name, position, linkedin
Employees companyName, companyWebsitedata.organization.organization, data.organization.website_url
Reverse email linkedin_urldata.linkedin
Reverse email profile fullName, jobTitle, companyName, companyWebsite, countrydata.full_name, data.position, data.company, data.website_url, data.countrydata.country is a two-letter country code.
Reverse email profile headline, summary, skills, jobs, educations, certificates, city, regionNo equivalent
Phone phonedata.e164_formatTomba also returns national and international formats. See Phone.
Phone line_typedata.line_typeTomba uses its own line type values.
Company name, domain, descriptiondata.name, data.domain, data.description
Company company_sizedata.metrics.employeesA range, such as 51-200.
Company linkedin_urldata.linkedin.handleThe handle only, not a URL.
Company industryNo equivalentGET /v1/domain-search returns it in data.organization.industries.
Verify emaildata.email.email
Verify verifieddata.email.statusSee Status mapping.
Verify providerdata.email.smtp_provider
Credits credits, verifier_creditsGET /v1/meSee Check usage.

The email finder returns its best match with a verification status in data.verification.status, including catch-all (accept_all) and unconfirmed (unknown) matches. If your code expects only verified addresses, keep results whose status is valid.

Status mapping

Findymail's verifier returns a boolean. Tomba returns a detailed status and a result verdict:

Findymail verifiedTomba statusTomba result
truevaliddeliverable
falseinvalidundeliverable
falseaccept_all or unknownrisky
falsedisposableEmpty string

Compare status case-insensitively. Each value is defined in Status values.

Error mapping

FindymailTombaWhat to do
401 Unauthenticated.400 authentication_failed (missing or malformed), 400 api_key_expired, 401 authentication_failed (wrong key or secret)Check both headers; rotate an expired key.
402 Not enough credits402 quota_exceededWait for your usage window to renew or add credits.
423 Subscription is paused401 authentication_failedThe message says the subscription has expired. Renew it.
422 invalid data422 params_invalidFix the parameter named in the message.
404 company not found200 with an errors body, type not_foundCheck the body for errors on /v1/companies/find.
429 Too Many Attempts.429 rate_limitRetry after the Retry-After delay; see Handle 429 responses.
No equivalent400 unknown_recordThe email finder received a disposable or webmail domain.
No equivalent451 claimed_emailThe owner of the address asked Tomba to stop processing it. Remove it from your data.

Error responses don't consume credits. Every type is listed in Errors.

Bulk and async jobs

A Tomba lookup always returns its result in the response. With webhook_url it also posts a copy, but the request doesn't move to the background as it does on Findymail.

Findymail has no bulk endpoint. To process a list with Tomba, replace per-contact loops with a bulk job: finder for names and companies, linkedin for profile URLs, enrich for email addresses, search for domains, and verifier for verification. Email finder jobs take a CSV file:

TerminalCode
curl -X POST "https://api.tomba.io/v1/bulk/finder" \ -H "X-Tomba-Key: $TOMBA_API_KEY" \ -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \ -F "name=Conference leads" \ -F "file=@leads.csv;type=text/csv" \ -F "full_name_field_index=0" \ -F "domain_field_index=1"

Tomba treats the first row of the file as a header. Launch the job, poll its progress, and download the results as shown in Lifecycle. Input formats per type are in Bulk types, and a job is charged when you first download its results; see Billing.

Code example

This function replaces a call to POST /api/search/name and returns Findymail's contact shape, or null when no address 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, }; // Findymail's `domain` field accepts a domain or a company name. // Tomba takes a domain as `domain` and a company name as `company`. async function findFromName(name, domainOrCompany) { const url = new URL("https://api.tomba.io/v1/email-finder"); url.searchParams.set("full_name", name); url.searchParams.set( domainOrCompany.includes(".") ? "domain" : "company", domainOrCompany, ); 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 { email, full_name, website_url, verification } = body.data; if (!email) return null; return { contact: { name: full_name, domain: website_url, email }, status: verification?.status ?? null, }; } console.log(await findFromName("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 a bearer token.
  2. Change each POST with a JSON body into a GET with query parameters, and send Findymail's domain value as domain or company.
  3. Read results from data instead of contact, treat data.email: null as no match, and filter on data.verification.status if you need verified addresses only.
  4. Handle 402 as before, retry 429 after Retry-After, skip 400 unknown_record domains, and remove addresses that return 451.
  5. Move large lists from per-contact loops to bulk jobs, and set webhook_url or poll /progress to know when they end.
  6. Run the same sample of contacts through both services and compare the results before you switch production traffic.
Last modified on September 30, 2026
ProspeoApollo.io
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