Copy page

Email finders

Migrate from Hunter (email finder)

This guide maps the Hunter API v2 Domain Search, Email Finder, Email Count, Account, and People, Companies, and Combined enrichment endpoints to Tomba. Hunter's Email Verifier is covered in Migrate from Hunter (email verifier). Hunter API behavior checked on 2026-09-29 against the Hunter API v2 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.hunter.io/v2 with https://api.tomba.io/v1.

Authentication changes

Hunter accepts the key as the api_key parameter, the X-API-KEY header, or a bearer token. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and doesn't accept credentials in the query string:

Code
# Hunter
curl "https://api.hunter.io/v2/email-finder?domain=stripe.com&first_name=Jane&last_name=Doe" \
  -H "X-API-KEY: $HUNTER_API_KEY"

# Tomba
curl "https://api.tomba.io/v1/email-finder?domain=stripe.com&first_name=Jane&last_name=Doe" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY"

Tomba API keys expire; plan their rotation with Key expiry.

Domain search

Parameters

Response fields

Tomba also returns company details in data.organization, such as industries, company_size, location, and social_links.

Email finder

Parameters

Response fields

Tomba also returns full_name, pattern, department, type, country, and gender.

Email count and enrichment

Error mapping

Hunter returns errors as an array of {id, code, details}. Tomba returns a single errors object with type, message, and code. The meaning of 403 and 429 also changes:

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

Bulk and async jobs

Hunter runs bulk Domain Search and Email Finder lists from its dashboard, and its API endpoints take one item per request. Tomba runs lists through the API as bulk jobs:

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

Code example

This function replaces a call to Hunter's Email Finder and returns Hunter's field names, 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,
};

// Accepts Hunter's parameters: domain or company, and first_name + last_name or full_name.
async function emailFinder(params) {
    const url = new URL("https://api.tomba.io/v1/email-finder");
    for (const key of [
        "domain",
        "company",
        "first_name",
        "last_name",
        "full_name",
    ]) {
        if (params[key]) url.searchParams.set(key, params[key]);
    }

    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;
    return {
        first_name: found.first_name,
        last_name: found.last_name,
        email: found.email,
        score: found.score,
        domain: found.website_url,
        accept_all: found.accept_all,
        position: found.position,
        twitter: found.twitter,
        linkedin_url: found.linkedin,
        company: found.company,
        sources: (found.sources ?? []).map(({ website_url, ...source }) => ({
            domain: website_url,
            ...source,
        })),
        verification: found.verification ?? null,
    };
}

console.log(
    await emailFinder({
        domain: "stripe.com",
        first_name: "Jane",
        last_name: "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, X-API-KEY, or a bearer token.
2. Change the base URL, convert offset to page, send linkedin_handle lookups to /v1/linkedin, and filter results in code where Tomba has no filter.
3. Update response parsing: value becomes email, source domain becomes website_url, and the domain search company fields move under data.organization.
4. Swap error handling: 402 replaces Hunter's 429, 429 replaces Hunter's 403, and errors is an object, not an array.
5. Move list processing to bulk jobs.
6. Run the same sample of domains and people through both services and compare the results before you switch production traffic.