Copy page

Phone finders

Migrate from Lusha

This guide maps the phone lookups of Lusha's Person API (GET /v2/person, POST /v2/person) and the v3 Search and Enrich Contacts endpoints to Tomba. Lusha API behavior checked on 2026-09-30 against the Lusha API reference and Lusha API error codes.

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.lusha.com with https://api.tomba.io. Tomba picks the endpoint by the identifier you have:

Authentication changes

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

Code
# Lusha
curl -G "https://api.lusha.com/v2/person" \
  --data-urlencode "email=jane.doe@stripe.com" \
  -H "api_key: $LUSHA_API_KEY"

# Tomba
curl -G "https://api.tomba.io/v1/phone-finder" \
  --data-urlencode "email=jane.doe@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

Lusha returns the person in contact.data. The Tomba phone finder returns the number itself in data, or an array of numbers with full=true:

Tomba also returns valid, carrier, region, and timezones for each number, and the email, domain, or linkedin it was found for. Every field is described in Phone response.

Status mapping

Every line_type value is defined in Line types. With full=true, filter on valid if you only want valid numbers.

Error mapping

Lusha returns errors as {statusCode, message, errors}. Tomba returns an errors object with type, message, and code:

Error responses don't consume credits. Every type is listed in Errors, and Tomba's rate limit headers are in Rate limit headers.

Bulk and async jobs

Lusha's POST /v2/person and v3 contact endpoints answer up to 100 contacts in one synchronous response, keyed by your contactId or clientReferenceId. A Tomba bulk job runs in the background: create it, launch it, poll its progress, and download the results as CSV. For a few contacts, send single requests instead.

A JSON list is de-duplicated and reordered, so join the results back to your records on the email address or LinkedIn URL, not on position. The requests for each step are in Lifecycle, and webhook_url sends an event when a job ends; see Bulk job events. A job is charged when you first download its results; see Billing.

Code example

This function replaces a GET /v2/person phone lookup and returns Lusha's phoneNumbers shape, or null when no number is found. It sends an email address or LinkedIn URL to the phone finder, and a name and company to the email finder with enrich_mobile=true. 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,
};

async function tombaGet(path, params) {
    const url = new URL(path, "https://api.tomba.io");
    for (const [key, value] of Object.entries(params)) {
        if (value) url.searchParams.set(key, value);
    }
    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}`,
        );
    }
    return body.data;
}

// Accepts Lusha's parameters: email, linkedinUrl, or firstName + lastName
// with companyDomain or companyName.
async function findPhones(params) {
    let numbers;
    if (params.email || params.linkedinUrl) {
        numbers = await tombaGet("/v1/phone-finder", {
            email: params.email,
            linkedin: params.linkedinUrl,
            full: "true",
        });
    } else {
        const person = await tombaGet("/v1/email-finder", {
            first_name: params.firstName,
            last_name: params.lastName,
            domain: params.companyDomain,
            company: params.companyName,
            enrich_mobile: "true",
        });
        numbers = person.phone_data ?? [];
    }

    if (numbers.length === 0) return null;
    return {
        phoneNumbers: numbers.map((phone) => ({
            number: phone.e164_format,
            lineType: phone.line_type,
            valid: phone.valid,
        })),
    };
}

console.log(await findPhones({ email: "jane.doe@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 api_key.
2. Route each lookup by its identifier: email address or LinkedIn URL to /v1/phone-finder, name and company to /v1/email-finder with enrich_mobile=true. Replace personId lookups with one of these.
3. Read numbers from data (with full=true) or data.phone_data instead of contact.data.phoneNumbers, and map phoneType to line_type.
4. Treat an empty data array as no match, in place of EMPTY_DATA and 404.
5. Swap error handling: 422 replaces 400 and 412, 451 carries a claimed_* type, and errors is an object.
6. Move batches of up to 100 contacts to Tomba bulk jobs, or loop over single requests.
7. Run the same sample of contacts through both services and compare the numbers before you switch production traffic.