Copy page

Phone finders

Migrate from Kaspr

This guide maps Kaspr's Get LinkedIn Profile endpoint and its key endpoints to Tomba: phone numbers to Phone Finder, work emails to LinkedIn Finder. Kaspr API behavior checked on 2026-09-30 against the Kaspr 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.developers.kaspr.io with https://api.tomba.io/v1. Kaspr returns phones and emails from one POST request; Tomba splits them across two GET endpoints that both take the LinkedIn profile URL.

Authentication changes

Kaspr takes the key in an authorization: Bearer header and needs accept-version: v2.0 on the profile endpoint. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and has no version header:

Code
# Kaspr
curl -X POST "https://api.developers.kaspr.io/profile/linkedin" \
  -H "authorization: Bearer $KASPR_API_KEY" \
  -H "accept-version: v2.0" \
  -H "Content-Type: application/json" \
  -d '{"id": "jane-doe", "name": "Jane Doe", "dataToGet": ["phone"]}'

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

Kaspr's body fields become query parameters:

Response field mapping

Kaspr returns the person under profile. Tomba returns data: a phone number object on Phone Finder, and a person object on LinkedIn Finder.

When Phone Finder finds nothing, the status is 200, data is an empty array, and the response repeats the linkedin you sent, reduced to its permalink such as jane-doe.

Status mapping

Kaspr returns phones and emails without a status. Tomba adds one to each result:

To keep only dialable numbers, filter Phone Finder results on valid: true, and on line_type MOBILE if you call mobiles only.

Error mapping

Kaspr returns {message, reason}. Tomba returns an errors object with type, message, and code:

Also handle Tomba's 400 and 401 authentication_failed for missing or wrong credentials, 400 api_key_expired for an expired key, 422 params_invalid for a malformed LinkedIn URL or a Phone Finder request without email, domain, or linkedin, and 451 claimed_linkedin or 451 claimed_email when the person asked Tomba to stop processing their data. Error responses don't consume credits; every type is listed in Errors.

Kaspr's rate-limit headers (X-Daily-RateLimit-*, X-Hourly-RateLimit-*, X-Minutely-*) have Tomba counterparts listed in Rate limit headers.

Bulk and async jobs

Kaspr's API takes one profile per request. Tomba also runs lists of profiles as bulk jobs:

Each job is created, launched, polled, and downloaded as CSV; see Lifecycle. To be notified when a job ends, set webhook_url; see Bulk job events. A job is charged when you first download its results; see Billing.

Code example

This function replaces a call to Kaspr's Get LinkedIn Profile endpoint and returns Kaspr's profile field names, or null when Tomba finds neither a number nor an 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,
};

async function tomba(path, params) {
    const url = new URL(`https://api.tomba.io/v1/${path}`);
    for (const [key, value] of Object.entries(params)) {
        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 Kaspr's body: id (profile ID or URL) and dataToGet.
async function getLinkedinProfile({ id, dataToGet = ["phone", "workEmail"] }) {
    const linkedin = id.startsWith("http")
        ? id
        : `https://www.linkedin.com/in/${id}`;

    const [phones, person] = await Promise.all([
        dataToGet.includes("phone")
            ? tomba("phone-finder", { linkedin, full: "true" })
            : [],
        dataToGet.includes("workEmail")
            ? tomba("linkedin", { url: linkedin })
            : null,
    ]);

    const numbers = phones.map((phone) => phone.intl_format);
    const starry = phones.find((phone) => phone.valid) ?? phones[0];
    if (numbers.length === 0 && !person?.email) return null;

    return {
        id,
        name: person?.full_name ?? null,
        firstName: person?.first_name ?? null,
        lastName: person?.last_name ?? null,
        professionalEmails: person?.email ? [person.email] : [],
        starryProfessionalEmail: person?.email ?? null,
        phones: numbers,
        starryPhone: starry?.intl_format ?? null,
        title: person?.position ?? null,
        companyName: person?.company ?? null,
    };
}

console.log(
    await getLinkedinProfile({
        id: "https://www.linkedin.com/in/jane-doe",
        dataToGet: ["phone", "workEmail"],
    }),
);

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 the authorization: Bearer and accept-version headers.
2. Replace each POST /profile/linkedin with GET requests: Phone Finder for phones, LinkedIn Finder for work emails, and send full profile URLs instead of profile IDs.
3. Update response parsing: read numbers from data or data[] instead of profile.phones, handle an empty data array as no result, and drop code that reads personal emails.
4. Replace requiredData with checks in your code, and filter numbers on valid and line_type.
5. Swap error handling to read the errors object, and move to Tomba's rate-limit headers and Retry-After.
6. Move list processing to phone-finder and linkedin bulk jobs.
7. Run the same sample of LinkedIn profiles through both services and compare the results before you switch production traffic.