Copy page

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.

Authentication changes

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

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

Response field mapping

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

Status mapping

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:

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.

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.