Copy page

Email finders

Migrate from Voila Norbert

This guide maps the Voila Norbert API (/search/name, /search/domain, /contacts, /massives, /verifier, /enrich, and /account) to Tomba. Voila Norbert API behavior checked on 2026-09-30 against the Voila Norbert 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.
• Voila Norbert can return a name search while it's still running, with searching: true, and you poll the contact until it finishes. Tomba returns the finished result in the response. Set your HTTP client timeout to at least 180 seconds.

Endpoint mapping

Replace the base URL https://api.voilanorbert.com/2018-01-08 with https://api.tomba.io/v1. Voila Norbert searches are POST requests; Tomba lookups are GET requests with query parameters.

Authentication changes

Voila Norbert uses HTTP Basic authentication with any user name and the API token as the password. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

Code
# Voila Norbert
curl -X POST "https://api.voilanorbert.com/2018-01-08/search/name" \
  -u "any:$NORBERT_API_TOKEN" \
  -d "name=Jane Doe" \
  -d "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

Response field mapping

Tomba wraps every result in data.

Tomba also returns position, linkedin, country, and the sources where the address was found; see Person. The verifier fields are in Email verifier response.

Status mapping

Voila Norbert scores a found address 100 when it was verified against the mail server, 80 when it wasn't, and 5 when it comes only from external sources. Tomba's data.score is computed differently, so read the mail server check from data.verification.status instead:

Tomba can also return accept_all, invalid, or unknown, or null when the address hasn't been verified.

For the verifier, map the webhook result flags to Tomba's result:

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

Error mapping

Tomba returns an errors object with type, message, and code:

Also handle 451 claimed_email when the owner of an address asked Tomba to stop processing it. Error responses don't consume credits; every type is listed in Errors.

Bulk and async jobs

Voila Norbert's /massives/ endpoint takes CSV content or a file URL, and sends the result file to a required webhook. Tomba's finder bulk job takes an uploaded CSV file and sends no webhook: you poll its progress and download the results.

Verification and enrichment lists become verifier and enrich jobs; see Email verifier and Email enrichment. 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 POST /search/name call and its polling. It returns Voila Norbert's contact field names, with email set to 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 Voila Norbert's parameters: name, and domain or company.
async function searchName({ name, domain, company }) {
    const url = new URL("https://api.tomba.io/v1/email-finder");
    url.searchParams.set("full_name", name);
    if (domain) url.searchParams.set("domain", domain);
    if (company) url.searchParams.set("company", company);

    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;
    return {
        name,
        searching: false,
        email: found.email
            ? {
                  email: found.email,
                  score: found.score,
                  status: found.verification?.status?.toLowerCase() ?? null,
              }
            : null,
        company: { name: found.company, url: found.website_url },
    };
}

console.log(await searchName({ name: "Jane 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 Basic authentication.
2. Change the base URL, send lookups as GET requests, and send name as full_name.
3. Remove the searching check and the /contacts/{id} polling loop.
4. Replace score thresholds with data.verification.status, comparing it case-insensitively.
5. Move /massives/, /verifier/upload, and /enrich/upload lists to finder, verifier, and enrich bulk jobs, setting zero-based field indexes where the headers don't name the columns, and replace their webhooks with webhook_url.
6. Handle 402 for exhausted credits, retry 429 after Retry-After, and drop addresses that return 451.
7. Run the same sample of people and addresses through both services and compare the results before you switch production traffic.