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?

O tempo de processamento depende do tamanho da lista e das consultas necessárias. Consulte o status da tarefa ou configure um webhook para saber quando ela terminar.

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.

Obter chave de API grátis Referência da API

Names, with a domain or company nameAté 10,000 linhas

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 · requisição

Massa Email Finder é uma requisição HTTPS

Envie os parâmetros com sua chave e seu secret. Todos os SDKs, a CLI e o servidor MCP fazem esta mesma chamada.

type: finder
list | data | file: Names, with a domain or company name
launch: true inicia o job imediatamente
webhook_url: Recebe um evento assinado quando o job termina
rows: Até 10,000 por 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 · resposta

O que volta

JSON, igual em todas as linguagens. Campos que a Tomba não conhece vêm como null, nunca adivinhados.

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
  }
}

Cada linha, como GET /email-finder a retorna

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 · custo e limites

Quanto custa uma chamada

Uma chamada só é cobrada na condição abaixo. Os limites de requisições dependem do seu plano.

// custo

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

Ainda tem dúvidas? Visite a central de ajuda

Faça sua primeira chamada em um minuto

Conta gratuita, chave de API real, os mesmos endpoints que os clientes Enterprise usam.

1Crie uma conta gratuita25 buscas por mês. Sem cartão.

2Copie sua chave e seu secretEm Chaves de API, no painel.

3Chame a APICole a requisição; a resposta vem em 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

Massa Email Finder é uma requisição HTTPS

O que volta

Quanto custa uma chamada

Endpoints relacionados

Frequently Asked Questions

Faça sua primeira chamada em um minuto