How does the Bulk Email Finder API work?

Create a bulk operation by uploading name/domain pairs, then launch the operation. The API processes all lookups asynchronously. Use webhooks or polling to get notified when processing completes, then download the results.

What is the maximum batch size?

You can process up to 10,000 name/domain lookups per bulk operation. For larger datasets, create multiple bulk operations.

What data format is required?

Upload data with columns for first_name, last_name, and domain (company website). The API will find the most likely email address for each person.

How long does processing take?

Il tempo di elaborazione dipende dalla dimensione della lista e dalle ricerche necessarie. Interroga lo stato del job o imposta un webhook per sapere quando termina.

What results are returned?

Each result includes the email address, full name, company, position, confidence score, verification status, and sources. Results can be downloaded as CSV or JSON.

Are webhooks supported?

Yes, configure a webhook URL to receive a notification when your bulk operation completes. The webhook payload includes the bulk_id and status.

How do I check operation status?

Use GET /v1/bulk/email-finder/{bulk_id} to check the status of your operation. Status values include pending, processing, completed, and failed.

How are credits calculated?

Each successful email found counts as 1 request. Lookups that don't return results are not counted against your quota.

What lookup quality gives the best results?

Use accurate first and last names with the correct company root domain. Clean input data significantly improves match quality and confidence.

Can I verify found emails in the same workflow?

Yes. After the bulk job completes, run the results through Bulk Email Verifier to reduce bounce risk before campaign launch.

// post /v1/bulk/finder

Bulk Email Finder API

Resolve thousands of name and company combinations into verified professional emails through one bulk API job.

Ottieni una chiave API gratuita Riferimento API

Names, with a domain or company nameFino a 10,000 righe

POST /bulk/finder

curl -X POST "https://api.tomba.io/v1/bulk/finder" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Conference leads","data":[["first_name","last_name","company_website"],["Richard","Hendricks","piedpiper.com"]],"launch":true,"webhook_url":"https://hooks.example.com/tomba"}'

const res = await fetch("https://api.tomba.io/v1/bulk/finder", {
  method: "POST",
  headers: {
    "X-Tomba-Key": process.env.TOMBA_API_KEY,
    "X-Tomba-Secret": process.env.TOMBA_SECRET_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "Conference leads",
    "data": [
      [
        "first_name",
        "last_name",
        "company_website"
      ],
      [
        "Richard",
        "Hendricks",
        "piedpiper.com"
      ]
    ],
    "launch": true,
    "webhook_url": "https://hooks.example.com/tomba"
  })
});
const { data } = await res.json(); // { id }

import os, requests

res = requests.post(
    "https://api.tomba.io/v1/bulk/finder",
    headers={
        "X-Tomba-Key": os.environ["TOMBA_API_KEY"],
        "X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
    },
    json={
      "name": "Conference leads",
      "data": [
        [
          "first_name",
          "last_name",
          "company_website"
        ],
        [
          "Richard",
          "Hendricks",
          "piedpiper.com"
        ]
      ],
      "launch": True,
      "webhook_url": "https://hooks.example.com/tomba"
    },
)
job_id = res.json()["data"]["id"]

// 01 · richiesta

Bulk Email Finder è una sola richiesta HTTPS

Invia i parametri con la tua chiave e il tuo secret. Ogni SDK, la CLI e il server MCP fanno questa stessa chiamata.

type: finder
list | data | file: Names, with a domain or company name
launch: true avvia subito il job
webhook_url: Riceve un evento firmato quando il job termina
rows: Fino a 10,000 per job

POST /bulk/finder

curl -X POST "https://api.tomba.io/v1/bulk/finder" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Conference leads","data":[["first_name","last_name","company_website"],["Richard","Hendricks","piedpiper.com"]],"launch":true,"webhook_url":"https://hooks.example.com/tomba"}'

const res = await fetch("https://api.tomba.io/v1/bulk/finder", {
  method: "POST",
  headers: {
    "X-Tomba-Key": process.env.TOMBA_API_KEY,
    "X-Tomba-Secret": process.env.TOMBA_SECRET_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "Conference leads",
    "data": [
      [
        "first_name",
        "last_name",
        "company_website"
      ],
      [
        "Richard",
        "Hendricks",
        "piedpiper.com"
      ]
    ],
    "launch": true,
    "webhook_url": "https://hooks.example.com/tomba"
  })
});
const { data } = await res.json(); // { id }

import os, requests

res = requests.post(
    "https://api.tomba.io/v1/bulk/finder",
    headers={
        "X-Tomba-Key": os.environ["TOMBA_API_KEY"],
        "X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
    },
    json={
      "name": "Conference leads",
      "data": [
        [
          "first_name",
          "last_name",
          "company_website"
        ],
        [
          "Richard",
          "Hendricks",
          "piedpiper.com"
        ]
      ],
      "launch": True,
      "webhook_url": "https://hooks.example.com/tomba"
    },
)
job_id = res.json()["data"]["id"]

// 02 · risposta

Cosa ricevi

JSON, uguale in ogni linguaggio. I campi che Tomba non conosce sono null, mai indovinati.

GET/email-finderCampo

data.emailstring | null: The address, or null when none is found
data.scoreinteger: Confidence from 0 to 100
data.verification.statusstring | null: valid, accept_all, invalid or unknown, with verification.date
data.full_name, data.position, data.departmentstring | null: Name, job title and team
data.typestring | null: personal or generic (a role address such as sales@)
data.linkedin, data.twitterstring | null: Public profiles
data.sources[]array | null: Up to 20 public pages where the address was found, with dates
data.accept_allboolean | null: The domain accepts mail for any address (catch-all)
data.phone_numberboolean: Tomba holds a phone number for the person
data.phone_data[]array: The numbers, when you send enrich_mobile (each as in Phone Finder)

POST /bulk/finder

201 Created

{
  "data": {
    "id": 1042
  }
}

Ogni riga, come la restituisce GET /email-finder

200 OK

{
  "data": {
    "email": "richard@piedpiper.com",
    "first_name": "Richard",
    "last_name": "Hendricks",
    "full_name": "Richard Hendricks",
    "website_url": "piedpiper.com",
    "company": "Pied Piper",
    "pattern": "{first}",
    "department": "executive",
    "type": "personal",
    "position": "CEO",
    "country": "US",
    "gender": "male",
    "twitter": null,
    "linkedin": "https://www.linkedin.com/in/richard-hendricks",
    "score": 100,
    "accept_all": false,
    "phone_number": true,
    "verification": {
      "date": "2025-01-15T10:32:00+01:00",
      "status": "valid"
    },
    "sources": [
      {
        "uri": "https://piedpiper.com/blog/engineering",
        "website_url": "piedpiper.com",
        "extracted_on": "2024-06-01T09:14:07+01:00",
        "last_seen_on": "2025-01-10T17:02:44+01:00",
        "still_on_page": true
      }
    ],
    "phone_data": []
  }
}

// 03 · costi e limiti

Quanto costa una chiamata

Una chiamata viene addebitata solo alla condizione indicata sotto. I limiti di frequenza dipendono dal tuo piano.

// costo

1 search credit per row whose address is verified valid. Plus 5 per row with phone data.

Charged once, at the first download; later downloads are free

Jobs created: 15 per day for each type
Running jobs: 2 per type
Downloads: 25 per day for each job
Request size: 4 MB (CSV, list or rows)

// faq

Frequently Asked Questions

Ha altre domande? Visita il centro assistenza

Fai la tua prima chiamata in un minuto

Account gratuito, vera chiave API, gli stessi endpoint usati dai clienti Enterprise.

1Crea un account gratuito25 ricerche al mese. Senza carta.

2Copia la chiave e il secretDa Chiavi API nella dashboard.

3Chiama l'APIIncolla la richiesta; la risposta è in JSON.

const res = await fetch("https://api.tomba.io/v1/email-finder?domain=piedpiper.com&first_name=Richard&last_name=Hendricks", { headers: { "X-Tomba-Key": process.env.TOMBA_API_KEY, "X-Tomba-Secret": process.env.TOMBA_SECRET_KEY } }); const { data } = await res.json();

import os, requests res = requests.get( "https://api.tomba.io/v1/email-finder?domain=piedpiper.com&first_name=Richard&last_name=Hendricks", headers={ "X-Tomba-Key": os.environ["TOMBA_API_KEY"], "X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"], }, ) data = res.json()["data"]

{ "data": { "email": "richard@piedpiper.com", "first_name": "Richard", "last_name": "Hendricks", "full_name": "Richard Hendricks", "website_url": "piedpiper.com", "company": "Pied Piper", "pattern": "{first}", "department": "executive", "type": "personal", "position": "CEO", "country": "US", "gender": "male", "twitter": null, "linkedin": "https://www.linkedin.com/in/richard-hendricks", "score": 100, "accept_all": false, "phone_number": true, "verification": { "date": "2025-01-15T10:32:00+01:00", "status": "valid" }, "sources": [ { "uri": "https://piedpiper.com/blog/engineering", "website_url": "piedpiper.com", "extracted_on": "2024-06-01T09:14:07+01:00", "last_seen_on": "2025-01-10T17:02:44+01:00", "still_on_page": true } ], "phone_data": [] } }

Bulk Email Finder API

Bulk Email Finder è una sola richiesta HTTPS

Cosa ricevi

Quanto costa una chiamata

Endpoint correlati

Frequently Asked Questions

Fai la tua prima chiamata in un minuto