Copy page

Email finders

Migrate from Skrapp

This guide maps the Skrapp API (the v2 finder, account, and list endpoints and the v3 verifier endpoints) to Tomba. Skrapp API behavior checked on 2026-09-30 against the Skrapp 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 host api.skrapp.io with api.tomba.io, and the /api/v2 and /v3 prefixes with /v1.

Authentication changes

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

Code
# Skrapp
curl "https://api.skrapp.io/api/v2/find?firstName=Jane&lastName=Doe&domain=stripe.com" \
  -H "X-Access-Key: $SKRAPP_API_KEY"

# Tomba
curl "https://api.tomba.io/v1/email-finder?first_name=Jane&last_name=Doe&domain=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

Tomba wraps every result in data.

Tomba's email finder also returns full_name, position, linkedin, country, and the sources where the address was found; see Person. The verifier fields are in Email verifier response.

Status mapping

Tomba also returns disposable, with an empty result, for a disposable domain. The email finder uses the same status values in data.verification.status. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

Skrapp returns an error code, a message, and the remaining credits. Tomba returns an errors object with type, message, and code:

Also handle 451 claimed_email when the owner of an address asked Tomba to stop processing it. Error responses don't consume credits; every type is listed in Errors.

Bulk and async jobs

Skrapp's bulk finder takes up to 100 people in a JSON body and returns a job id to poll. Its bulk verifier takes up to 50 addresses per request and answers directly. Tomba runs both as bulk jobs:

Each job is created, launched, polled, and downloaded as CSV; see Lifecycle. Row limits are in Bulk types. 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.

The tId you attach to each Skrapp row has no equivalent. Keep your own ID in an extra CSV column.

Code example

This function replaces a call to Skrapp's GET /api/v2/find and returns Skrapp's field names, or null where Skrapp returned 404. 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,
};

// Tomba status -> Skrapp email_status.
const SKRAPP_STATUS = {
    valid: "valid",
    accept_all: "catch-all",
    invalid: "invalid",
    unknown: "unknown",
};

// Accepts Skrapp's parameters: firstName, lastName, and domain or company.
async function find({ firstName, lastName, domain, company }) {
    const url = new URL("https://api.tomba.io/v1/email-finder");
    url.searchParams.set("first_name", firstName);
    url.searchParams.set("last_name", lastName);
    if (domain) url.searchParams.set("domain", domain);
    if (company) url.searchParams.set("company", company);

    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 found = body.data;
    if (!found.email) return null;
    const status = found.verification?.status?.toLowerCase();
    return {
        email: found.email,
        accuracy: found.score,
        firstName: found.first_name,
        lastName: found.last_name,
        companyName: found.company,
        quality: { status: SKRAPP_STATUS[status] ?? null },
    };
}

console.log(
    await find({ firstName: "Jane", lastName: "Doe", domain: "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 X-Access-Key.
2. Change the host and path prefixes, and rename firstName and lastName to first_name and last_name.
3. Treat data.email null as not found instead of a 404.
4. Translate email_status with the status mapping, comparing status case-insensitively, and call /v1/enrich where you used enrich=true.
5. Handle 402 for exhausted credits, retry 429 after Retry-After, and drop addresses that return 451.
6. Move find_bulk and verify_bulk batches to finder and verifier bulk jobs.
7. Run the same sample of people and addresses through both services and compare the results before you switch production traffic.