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
Phone finders
    OverviewLushaContactOutKasprRocketReach
Phone finders

Migrate from ContactOut

This guide maps the phone lookups of ContactOut's Contact Info API (single, bulk v1, and bulk v2), LinkedIn Profile API (from a LinkedIn URL and from an email address), People Enrich API, and Phone Number Checker to Tomba. ContactOut API behavior checked on 2026-09-30 against the ContactOut 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.
  • Set your HTTP client timeout to at least 180 seconds. Tomba returns the finished result in the response.

Endpoint mapping

Replace the base URL https://api.contactout.com with https://api.tomba.io.

ContactOutTombaNotes
GET /v1/people/linkedin with include_phone=trueGET /v1/phone-finder with linkedinFor email addresses, call GET /v1/linkedin.
GET /v1/linkedin/enrichGET /v1/phone-finder with linkedinReturns phone numbers only. For email addresses and profile data, call GET /v1/linkedin.
GET /v1/email/enrichGET /v1/enrich with enrich_mobile=trueReturns the person and their numbers in data.phone_data. For numbers only, call /v1/phone-finder with email.
POST /v1/people/enrich with linkedin_url or emailGET /v1/phone-finderSee Parameter mapping.
POST /v1/people/enrich with a name and company or company_domainGET /v1/email-finder with enrich_mobile=trueNumbers are in data.phone_data.
POST /v1/people/enrich with phoneNo equivalentTomba doesn't look people up by phone number. GET /v1/phone-validator checks the number itself.
GET /v1/people/linkedin/phone_statusGET /v1/linkedin, data.phone_numbertrue when Tomba has a number for the person. Unlike ContactOut's checker, this request can be charged; see Credit costs.
POST /v1/people/linkedin/batch, POST /v2/people/linkedin/batchA bulk job

Authentication changes

ContactOut reads the key from the token header. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

TerminalCode
# ContactOut curl -G "https://api.contactout.com/v1/people/linkedin" \ --data-urlencode "profile=https://www.linkedin.com/in/jane-doe" \ --data-urlencode "include_phone=true" \ -H "token: $CONTACTOUT_API_TOKEN" # Tomba curl -G "https://api.tomba.io/v1/phone-finder" \ --data-urlencode "linkedin=https://www.linkedin.com/in/jane-doe" \ --data-urlencode "full=true" \ -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

ContactOutTombaNotes
profile, linkedin_urllinkedinOn /v1/phone-finder. On /v1/linkedin the parameter is url.
emailemailOn /v1/phone-finder or /v1/enrich.
include_phone=true, include with phoneNot needed/v1/phone-finder returns only phone numbers. On the finder endpoints, enrich_mobile=true adds them.
full_name, first_name, last_namefull_name, first_name, last_nameOn /v1/email-finder with enrich_mobile=true.
companycompanyOn /v1/email-finder. Tomba takes one company per request; ContactOut takes an array.
company_domaindomainOn /v1/email-finder. One domain per request. On /v1/phone-finder, domain returns the company's number.
No equivalentfullfull=true returns every number found as an array; without it, data holds one number, preferring a valid one.
email_type, profile_only, phone, job_title, location, educationNo equivalent

Response field mapping

ContactOutTombaNotes
status_code in the bodyHTTP statusTomba doesn't repeat the status in the body.
profile.phone[] (array of numbers)data[].e164_format with full=trueAlso in intl_format, local_format, and rfc3966_format.
profile.phone (a string, from /v1/email/enrich)data.phone_data[].e164_formatOn /v1/enrich with enrich_mobile=true.
profile.urldata.linkedinOnly on a number found for the LinkedIn URL you sent.
profile.email, work_email, personal_emailNo equivalent on the phone finderCall /v1/linkedin or /v1/enrich for the email address.
profile.github, twitter, and profile detailsNo equivalent on the phone finderFor profile data, see the Person API.
Phone checker profile.phonedata.phone_number on /v1/linkedin

Tomba also returns valid, country_code, line_type, carrier, region, and timezones for each number. Every field is described in Phone response.

Status mapping

ContactOutTomba
404 with "message": "Not Found"200 with data as an empty array
Empty phone or phones array200 with data as an empty array
No equivalentvalid is false: the number isn't valid in its country's numbering plan
No equivalentline_type, such as MOBILE or FIXED_LINE; see Line types

With full=true, filter on valid if you only want valid numbers.

Error mapping

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

ContactOutTombaWhat to do
400 or 401 bad credentials or invalid headers400 authentication_failed (missing or malformed), 400 api_key_expired, 401 authentication_failed (wrong key or secret)Check both headers; rotate an expired key.
400 or 401 bad request or invalid input422 params_invalidFix the parameter named in the message. Sending none of email, domain, and linkedin to /v1/phone-finder also returns 422.
403 out of credits402 quota_exceededWait for your usage window to renew or add credits.
404 not found200 with data as an empty arrayTreat as no match.
429 rate limit, with retry-after429 rate_limit, with Retry-AfterRetry after the delay; see Handle 429 responses.
No equivalent451 claimed_email or 451 claimed_linkedinThe person asked Tomba to stop processing their data. Remove the record from your data.

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

Bulk and async jobs

ContactOut's bulk v1 endpoint answers up to 100 LinkedIn URLs synchronously, and bulk v2 returns a job_id to poll or a callback_url to notify. A Tomba bulk job runs in the background: create it, launch it, poll its progress, and download the results as CSV.

ContactOutTomba bulk type
profiles with include_phone: truephone-finder: a JSON list or CSV file of LinkedIn URLs or email addresses. See Phone finder.
GET /v2/people/linkedin/batch/{job_id}Poll the job's progress, then download its results. See Lifecycle.
callback_urlwebhook_url, which receives a signed event when the job ends. See Bulk job events.

ContactOut keys batch results by profile URL. A Tomba JSON list is de-duplicated and reordered, so join the CSV rows back to your records on the LinkedIn URL, not on position. A job is charged when you first download its results; see Billing.

Code example

This function replaces a call to GET /v1/people/linkedin with include_phone=true and returns ContactOut's profile.url and profile.phone fields, or null when no number is found. 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 ContactOut's profile parameter: a LinkedIn profile URL. async function linkedinPhones(profile) { const url = new URL("https://api.tomba.io/v1/phone-finder"); url.searchParams.set("linkedin", profile); url.searchParams.set("full", "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}`, ); } if (body.data.length === 0) return null; return { url: profile, phone: body.data.map((phone) => phone.e164_format), }; } console.log(await linkedinPhones("https://www.linkedin.com/in/jane-doe"));

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 token.
  2. Route each lookup by its identifier: LinkedIn URL or email address to /v1/phone-finder, name and company to /v1/email-finder with enrich_mobile=true. Drop lookups by phone number.
  3. Read numbers from data (with full=true) or data.phone_data instead of profile.phone, and use the HTTP status instead of status_code.
  4. Treat an empty data array as no match, in place of 404.
  5. Swap error handling: 402 replaces the out-of-credits 403, 422 covers invalid input, and 451 carries a claimed_* type.
  6. Move batch lookups to Tomba bulk jobs and poll their progress instead of waiting for callback_url.
  7. Run the same sample of profiles through both services and compare the numbers before you switch production traffic.
Last modified on September 30, 2026
LushaKaspr
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