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
    OverviewNeverBounceMillionVerifierBounceBanBouncerKickboxHunterZeroBounceEmailableClearoutDeBounce
Email finders
Phone finders
Email verifiers

Migrate from DeBounce

This guide maps the DeBounce API v1 (single validation, bulk upload and status, and balance) to the Tomba Email Verifier and bulk verifier jobs. DeBounce API behavior checked on 2026-09-30 against the DeBounce API reference and its result codes.

Before you begin

  • Get your API key (ta_…) and secret (ts_…); see Authentication.
  • Check what a verification costs in Credit costs and your plan's throttling in Limits by plan. Tomba throttles by requests per time window, not by concurrent calls.
  • Set your HTTP client timeout to at least 180 seconds. Tomba returns the finished result in the response.

Endpoint mapping

DeBounce uses two hosts, api.debounce.io and bulk.debounce.io. Tomba serves everything from api.tomba.io.

DeBounceTomba
GET https://api.debounce.io/v1/GET /v1/email-verifier
GET https://bulk.debounce.io/v1/upload/POST /v1/bulk/verifier, then PUT /v1/bulk/verifier/{id} to launch
GET https://bulk.debounce.io/v1/status/GET /v1/bulk/verifier/{id}/progress
The download_link from /v1/status/GET /v1/bulk/verifier/{id}/download
GET https://api.debounce.io/v1/balance/GET /v1/me

Authentication changes

DeBounce reads the key from the api query parameter. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and doesn't accept credentials in the query string:

TerminalCode
# DeBounce curl "https://api.debounce.io/v1/?api=$DEBOUNCE_API_KEY&email=jane.doe@stripe.com" # Tomba curl "https://api.tomba.io/v1/email-verifier?email=jane.doe@stripe.com" \ -H "X-Tomba-Key: $TOMBA_API_KEY" \ -H "X-Tomba-Secret: $TOMBA_SECRET_KEY"

If you call DeBounce from browser code with a public_ key, move the call to your server and keep the Tomba key and secret there (Security). Tomba API keys expire; plan their rotation with Key expiry.

Parameter mapping

DeBounceTombaNotes
apiX-Tomba-Key and X-Tomba-Secret headers
emailemailRequired. A malformed address returns 422 params_invalid instead of a result.
photo, appendNo equivalent
gsuiteNo equivalentEvery Tomba response includes data.email.accept_all.
Upload urlfile or listTomba doesn't fetch lists from a URL. Upload the CSV as file, or send list.
list_id{id} in the path

Response field mapping

DeBounce returns the result in a debounce object, with booleans and numbers as strings. Tomba nests the checks in data.email, uses JSON booleans, and lists the public pages where the address appears in data.sources. Field definitions are in Email verifier response.

DeBounceTombaNotes
debounce.emaildata.email.emailAn empty string when the domain is disposable.
debounce.code, debounce.reasondata.email.statusSee Status mapping.
debounce.resultdata.email.resultThe closest field; see Result values.
debounce.free_emaildata.email.webmail
debounce.roleNo equivalent
debounce.send_transactionalNo equivalent
debounce.did_you_meanNo equivalent
successHTTP status codeSee Error mapping.
balanceX-Verify-Remaining header, GET /v1/meSee Check usage.
debounce.errorerrors.message

Tomba also returns score, accept_all, block, greylisted, gibberish, disposable, mx_check, mx.records, smtp_provider, regex, and whois, which have no field in DeBounce's response.

Status mapping

DeBounce codereasonTomba statusTomba result
1SyntaxNo status. The request fails with 422 params_invalid.
2Spam TrapNo equivalent. Tomba returns the mailbox result.
3DisposabledisposableEmpty string
4Accept-Allaccept_allrisky
5Deliverablevaliddeliverable
6Invalidinvalidundeliverable
7Unknownunknownrisky

DeBounce reports role accounts in the role field rather than as code 8 in API responses; Tomba has no role flag. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

Both APIs signal failures with HTTP status codes. DeBounce's error body is {"debounce": {"error", "code"}, "success": "0"}; Tomba's is an errors object with type, message, and code.

DeBounceTombaWhat to do
401 Wrong API400 authentication_failed (missing or malformed), 400 api_key_expired, 401 authentication_failed (wrong key or secret)Check both headers; rotate an expired key.
402 Credits Low402 quota_exceeded on single requestsFor bulk jobs, the balance is checked at the first download instead; see Billing.
429 Maximum concurrent calls reached429 rate_limitRetry after the Retry-After delay; see Handle 429 responses.
Maximum number of API bulk verify requests reached429 rate_limit (running job limit)Wait for a running job to finish; see Limits.
400 URL parameter is not valid.No equivalentUpload the file instead of a URL.
List ID is not valid.GET /v1/bulk/verifier/{id} returns 404 unknown_recordCheck the job ID.
No equivalent422 params_invalidFix the parameter named in the message.
No equivalent408 proxy_errorThe mailbox check failed. Retry later.
No equivalent451 claimed_emailThe owner of the address asked Tomba to stop processing it. Remove it from your list.

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

Bulk and async jobs

DeBounceTomba
/v1/upload/ with the url of a file on your serverPOST /v1/bulk/verifier with name and a CSV file, or a newline-separated list of addresses
Validation starts on upload, or is queued behind a running jobLaunch the job: PUT /v1/bulk/verifier/{id}
Poll /v1/status/ for status and percentagePoll GET /v1/bulk/verifier/{id}/progress for status and progress until status is completed
Fetch the CSV from download_linkGET /v1/bulk/verifier/{id}/download?file=full
TerminalCode
curl -X POST "https://api.tomba.io/v1/bulk/verifier" \ -H "X-Tomba-Key: $TOMBA_API_KEY" \ -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \ -F "name=Newsletter list" \ -F "file=@emails.csv;type=text/csv" \ -F "email_field_index=0"

Tomba treats the first row of the file as a header. A DeBounce list with one address per line and no header loses its first address, so add a header row first. The launch, progress, and download requests are shown in Lifecycle. Row limits and daily job limits are in Limits, and a job is charged when you first download its results; see Billing.

Code example

This function replaces a call to api.debounce.io/v1/ and returns DeBounce's code and reason for the 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, }; // Tomba status -> DeBounce [code, reason] const CODES = { disposable: ["3", "Disposable"], accept_all: ["4", "Accept-All"], valid: ["5", "Deliverable"], invalid: ["6", "Invalid"], unknown: ["7", "Unknown"], }; async function validate(email) { const url = new URL("https://api.tomba.io/v1/email-verifier"); url.searchParams.set("email", email); const res = await fetch(url, { headers: TOMBA_HEADERS }); const body = await res.json(); if (body.errors) { // A malformed address (DeBounce code 1) fails with 422 params_invalid. throw new Error( `${res.status} ${body.errors.type}: ${body.errors.message}`, ); } const check = body.data.email; const [code, reason] = CODES[check.status.toLowerCase()] ?? CODES.unknown; return { email: check.email || email, code, reason, free_email: String(check.webmail), }; } console.log(await validate("jane.doe@stripe.com"));

Cutover checklist

  1. Store the Tomba key and secret as TOMBA_API_KEY and TOMBA_SECRET_KEY, send them as X-Tomba-Key and X-Tomba-Secret, and remove the api parameter from your URLs and logs.
  2. Point single validations at GET https://api.tomba.io/v1/email-verifier and set a client timeout of at least 180 seconds.
  3. Replace checks of success with HTTP status handling: 402, 422, 429 with Retry-After, 408, and 451.
  4. Translate code with the status mapping, comparing status case-insensitively, and read Tomba's booleans as JSON booleans rather than strings.
  5. Replace URL uploads with verifier bulk jobs: upload the CSV with a header row, launch, poll /progress, and download the CSV.
  6. Verify the same sample list with both services and compare the mapped results before you switch production traffic.
Last modified on September 30, 2026
ClearoutOverview
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