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 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.

Voila NorbertTombaNotes
POST /search/nameGET /v1/email-finder
GET /contacts/{id} (polling a search)No equivalentRemove the polling loop.
POST /search/domainGET /v1/domain-search
POST /verifier/upload for one addressGET /v1/email-verifierOne address per request.
POST /verifier/upload for a listPOST /v1/bulk/verifierSee Email verifier.
GET /verifier/{token}, .../downloadGET /v1/bulk/verifier/{id}/progress, .../downloadSee Lifecycle.
POST /enrich/upload for one addressGET /v1/enrich
POST /enrich/upload for a listPOST /v1/bulk/enrichSee Email enrichment.
GET /enrich/{token}, .../downloadGET /v1/bulk/enrich/{id}/progress, .../downloadSee Lifecycle.
POST /massives/POST /v1/bulk/finderSee Bulk and async jobs.
GET /massives/{id}GET /v1/bulk/finder/{id}/progress
DELETE /massives/{id}DELETE /v1/bulk/finder/{id}/delete
.../pause, .../resume, .../rerunNo equivalent
GET /lists/, POST /lists/GET /v1/leads_lists, POST /v1/leads_listsTomba doesn't add search results to a list; create leads with POST /v1/leads.
GET /account/, GET /organization/credits/GET /v1/meSee Check usage.

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:

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

Voila NorbertTombaNotes
Name search namefull_nameOr send first_name and last_name.
Name and domain search domaindomainThe email finder returns 400 unknown_record for a disposable or webmail domain.
Name and domain search companycompanyA domain gives better results.
Domain search pagepageTomba also takes limit; the cost depends on it. See Credit costs.
webhookwebhook_urlOptional in Tomba. The result is still returned in the response, and also posted to your URL when it qualifies. See Per-request callbacks. Bulk jobs send a signed event to their own webhook_url; see Bulk job events.
list_idNo equivalent
Verifier and enrich data, filelist, fileBulk jobs. A JSON list has one address per line, like data.

Response field mapping

Tomba wraps every result in data.

Voila NorbertTombaNotes
idNo equivalentThere's no contact record to fetch later.
searchingNo equivalentEvery Tomba response is final.
namedata.full_name
email.emaildata.emailnull when no address is found; the status is still 200.
email.scoredata.score, data.verification.statusSee Status mapping.
company.namedata.company
company.urldata.website_urlA domain in Tomba, not a URL.
Domain search result[].email.emaildata.emails[].email
Domain search result[].namedata.emails[].full_name
Domain search result[].is_newNo equivalent
Domain search totalmeta.total
Domain search has_nextmeta.current < meta.total_pages
Verifier emaildata.email.emailAn empty string when the domain is disposable.
Verifier is_deliverable, is_risky, is_bouncedata.email.resultSee Status mapping.
Verifier error_msgNo equivalent

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:

Voila Norbert email.scoreTomba verification.status
100valid

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:

Voila Norbert verifier flagTomba result
is_deliverabledeliverable
is_riskyrisky
is_bounceundeliverable

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:

Voila NorbertTombaWhat to do
400 bad request422 params_invalidFix the parameter named in the message.
401 authentication failed400 authentication_failed (missing or malformed), 400 api_key_expired, 401 authentication_failed (wrong key or secret)Check both headers; rotate an expired key.
402 insufficient credits402 quota_exceededWait for your usage window to renew or add credits.
402 missing webhookNot returnedTomba doesn't need a webhook.
429 rate limit exceeded429 rate_limitRetry after the Retry-After delay instead of X-RateLimit-Reset; see Handle 429 responses.
5xx500 api_errorRetry with backoff.

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.

Voila Norbert /massives/ fieldTomba finder fieldNotes
content, file_urlfileUpload the CSV as multipart/form-data.
col_namefirst_name_field_index and last_name_field_index, or full_name_field_indexTomba's indexes start at 0. Without them, the columns are found by their header.
col_domain, col_companydomain_field_index, company_name_field_index
webhookNo equivalentPoll the job's progress.
rerun_frequencyNo equivalentCreate a new job; running the same list again is charged again.
webhook_file_retention_timeNo equivalentResults can be downloaded for 180 days.

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.
Last modified on September 30, 2026
Apollo.ioSkrapp
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