Copy page

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.

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.

Code
# 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

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.

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

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:

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.

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.