Copy page

Phone finders

Migrate from RocketReach

This guide maps RocketReach's People Lookup, People Lookup Status, Bulk People Lookup, and Account endpoints to Tomba; the Universal API endpoints (/universal/*) aren't covered. RocketReach API behavior checked on 2026-09-30 against the RocketReach 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.rocketreach.co/api/v2 with https://api.tomba.io/v1. RocketReach's person lookup takes any identifier; Tomba has one endpoint per identifier:

Authentication changes

RocketReach takes the key in the Api-Key header, or in the deprecated api_key query parameter. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and doesn't accept credentials in the query string:

Code
# RocketReach
curl "https://api.rocketreach.co/api/v2/person/lookup?linkedin_url=https://www.linkedin.com/in/jane-doe" \
  -H "Api-Key: $ROCKETREACH_API_KEY"

# Tomba
curl "https://api.tomba.io/v1/linkedin?url=https://www.linkedin.com/in/jane-doe&enrich_mobile=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

RocketReach returns the profile at the top level. Tomba returns the person under data, and phone numbers under data.phone_data[] on the finders or data on Phone Finder.

Person and email fields

Tomba also returns department, gender, twitter, accept_all, and sources; see Person response.

Phone fields

On the finders, data.phone_number is true when Tomba has a number for the person; data.phone_data is filled only with enrich_mobile=true. When Phone Finder finds nothing, the status is 200 and data is an empty array.

Status mapping

RocketReach's lookup status (complete, failed, waiting, searching, progress) has no equivalent: every Tomba response is final. Email and phone statuses map as follows:

Tomba can also return disposable, or null when the address hasn't been verified. Compare status case-insensitively. Each value is defined in Status values.

Every value is listed in Line types.

Error mapping

RocketReach returns an error body with detail or message. Tomba returns an errors object with type, message, and code:

Also handle 451 claimed_email or 451 claimed_linkedin when the person asked Tomba to stop processing their data. Error responses don't consume credits; every type is listed in Errors. RocketReach's RR-Request-ID header corresponds to Tomba's request ID; see Request IDs.

Bulk and async jobs

RocketReach's POST /bulkLookup takes 1 to 100 queries and delivers results to a webhook. Tomba runs lists as bulk jobs, which can send an event to a webhook_url when they end:

Each job is created, launched, polled, and downloaded as CSV; see Lifecycle. A job is charged when you first download its results; see Billing. Limits are in Limits.

Code example

This function replaces a call to RocketReach's GET /person/lookup and returns RocketReach's field names, or null when no person 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,
};

const SMTP_VALID = {
    valid: "valid",
    invalid: "invalid",
    accept_all: "accept-all",
    unknown: "unknown",
};

// Accepts RocketReach's linkedin_url, email, or name + current_employer.
async function personLookup(params) {
    let path;
    const query = { enrich_mobile: "true" };
    if (params.linkedin_url) {
        path = "linkedin";
        query.url = params.linkedin_url;
    } else if (params.email) {
        path = "enrich";
        query.email = params.email;
    } else if (params.name && params.current_employer) {
        path = "email-finder";
        query.full_name = params.name;
        query.company = params.current_employer;
    } else {
        throw new Error(
            "Send linkedin_url, email, or name and current_employer",
        );
    }

    const url = new URL(`https://api.tomba.io/v1/${path}`);
    for (const [key, value] of Object.entries(query)) {
        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}`,
        );
    }

    const person = body.data;
    const phones = person.phone_data ?? [];
    if (!person.email && phones.length === 0) return null;

    const status = person.verification?.status?.toLowerCase();
    return {
        status: "complete",
        name: person.full_name,
        current_title: person.position,
        current_employer: person.company,
        current_employer_domain: person.website_url,
        linkedin_url: person.linkedin,
        country_code: person.country,
        recommended_professional_email: person.email,
        emails: person.email
            ? [
                  {
                      email: person.email,
                      smtp_valid: SMTP_VALID[status] ?? null,
                      type:
                          person.type === "generic"
                              ? "role-based"
                              : "professional",
                      last_validation_check: person.verification?.date ?? null,
                  },
              ]
            : [],
        phones: phones.map((phone) => ({
            number: phone.intl_format,
            e164: phone.e164_format,
            type: phone.line_type === "MOBILE" ? "mobile" : "other",
        })),
    };
}

console.log(
    await personLookup({
        linkedin_url: "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 Api-Key.
2. Route each lookup by identifier: LinkedIn URLs to /v1/linkedin, names and companies to /v1/email-finder, email addresses to /v1/enrich, and phone-only lookups to /v1/phone-finder. Add enrich_mobile=true where you need numbers.
3. Remove the /person/checkStatus polling and the lookup webhook handler, or pass webhook_url per request.
4. Update response parsing: read fields under data, numbers from data.phone_data, and treat data.email null or an empty data array as not found instead of 404.
5. Swap error handling: 402 replaces RocketReach's out-of-credits 403, 422 replaces 400, and errors is an object.
6. Move /bulkLookup batches to phone-finder, linkedin, and finder bulk jobs.
7. Run the same sample of people through both services and compare the results before you switch production traffic.