Copy page

Email finders

Migrate from Prospeo

This guide maps the Prospeo API (Enrich Person, Bulk Enrich Person, Enrich Company, Bulk Enrich Company, Search Person, Search Company, and Account Information) to Tomba. Prospeo API behavior checked on 2026-09-29 against the Prospeo API documentation.

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.
• Prospeo's Enrich Person takes whichever datapoints you have. Tomba has one endpoint per input: a name and company, a LinkedIn URL, or an email address. Route each call by the datapoint you send.

Endpoint mapping

Replace the host api.prospeo.io with api.tomba.io.

Authentication changes

Prospeo reads the key from the X-KEY header. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and its lookups are GET requests with query parameters instead of POST requests with JSON bodies:

Code
# Prospeo
curl -X POST "https://api.prospeo.io/enrich-person" \
  -H "X-KEY: $PROSPEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"only_verified_email": true, "data": {"full_name": "Jane Doe", "company_website": "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

Response field mapping

Tomba wraps every result in data. For Enrich Person calls answered by /v1/email-finder, /v1/linkedin, or /v1/enrich:

For Enrich Company calls answered by /v1/companies/find, the company is in data:

Field definitions are in Enrichment.

Status mapping

Tomba returns its best match with a status, including catch-all (accept_all) and unconfirmed (unknown) addresses. If you sent only_verified_email: true, keep only results whose status is valid. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

Prospeo returns errors with HTTP 400 and an error_code. Tomba uses a distinct HTTP status for each cause, with an errors object:

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

Bulk and async jobs

Prospeo's bulk endpoints answer up to 50 records in one synchronous response. A Tomba bulk job runs in the background: create it, launch it, poll its progress, and download the results as CSV. For a few records, send single requests instead.

The requests for each step are in Lifecycle, and webhook_url sends an event when a job ends; see Bulk job events. A job is charged when you first download its results; see Billing.

Code example

This function replaces an Enrich Person call made with a full name, a company website, and only_verified_email: true, and returns Prospeo's field names. 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,
};

async function enrichPerson(fullName, companyWebsite) {
    const url = new URL("https://api.tomba.io/v1/email-finder");
    url.searchParams.set("full_name", fullName);
    url.searchParams.set("domain", companyWebsite);

    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}`,
        );
    }

    // Like only_verified_email: true, return only addresses verified as valid.
    const found = body.data;
    if (!found.email || found.verification?.status?.toLowerCase() !== "valid") {
        return { error: true, error_code: "NO_MATCH" };
    }
    return {
        error: false,
        person: {
            full_name: found.full_name,
            first_name: found.first_name,
            last_name: found.last_name,
            current_job_title: found.position || null,
            linkedin_url: found.linkedin || null,
            email: { status: "VERIFIED", email: found.email },
        },
        company: { name: found.company, domain: found.website_url },
    };
}

console.log(await enrichPerson("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 X-KEY.
2. Route each Enrich Person call by its datapoint: name and company to /v1/email-finder, LinkedIn URL to /v1/linkedin, email address to /v1/enrich.
3. Turn JSON bodies into query parameters: company_website becomes domain and company_name becomes company.
4. Read data.email and data.verification.status, and keep only valid addresses where you used only_verified_email.
5. Replace error_code handling with HTTP status handling: 402, 422, 429 with Retry-After, and 451.
6. Move bulk enrichment to Tomba bulk jobs, or loop over single requests for small batches.
7. Run the same sample of people and companies through both services and compare the results before you switch production traffic.