// post /v1/bulk/phone-finder
API do Buscador de telefone em massa
Transforme grandes bases de contatos em telefones utilizáveis, com tipo de linha e operadora, em um único job assíncrono.
Email addresses, LinkedIn URLs or domainsAté 10,000 linhas
curl -X POST "https://api.tomba.io/v1/bulk/phone-finder" \
-H "X-Tomba-Key: $TOMBA_API_KEY" \
-H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Phone Finder job","list":"richard@piedpiper.com","launch":true,"webhook_url":"https://hooks.example.com/tomba"}'const res = await fetch("https://api.tomba.io/v1/bulk/phone-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": "Phone Finder job",
"list": "richard@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/phone-finder",
headers={
"X-Tomba-Key": os.environ["TOMBA_API_KEY"],
"X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
},
json={
"name": "Phone Finder job",
"list": "richard@piedpiper.com",
"launch": True,
"webhook_url": "https://hooks.example.com/tomba"
},
)
job_id = res.json()["data"]["id"]// 01 · requisição
Massa Phone 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
- phone-finder
- list | data | file
- Email addresses, LinkedIn URLs or domains
- launch
- true inicia o job imediatamente
- webhook_url
- Recebe um evento assinado quando o job termina
- rows
- Até 10,000 por job
curl -X POST "https://api.tomba.io/v1/bulk/phone-finder" \
-H "X-Tomba-Key: $TOMBA_API_KEY" \
-H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Phone Finder job","list":"richard@piedpiper.com","launch":true,"webhook_url":"https://hooks.example.com/tomba"}'const res = await fetch("https://api.tomba.io/v1/bulk/phone-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": "Phone Finder job",
"list": "richard@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/phone-finder",
headers={
"X-Tomba-Key": os.environ["TOMBA_API_KEY"],
"X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
},
json={
"name": "Phone Finder job",
"list": "richard@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
/phone-finderdataobject | array- The number; an array with full=true, and an empty array when none is found
data.validboolean | null- Whether the number is a valid phone number
data.intl_format, data.e164_format, data.local_formatstring | null- The number in international, E.164 and national formats
data.country_codestring | null- Country of the number (ISO code)
data.line_typestring | null- MOBILE, FIXED_LINE, FIXED_LINE_OR_MOBILE, VOIP, TOLL_FREE…
data.carrierstring | null- The network operator
data.region, data.timezonesobject | null, array | null- Where the number is registered, and its time zones
POST /bulk/phone-finder
201 Created
{
"data": {
"id": 1042
}
}Cada linha, como GET /phone-finder a retorna
200 OK
{
"email": "richard@piedpiper.com",
"data": {
"email": "richard@piedpiper.com",
"valid": true,
"local_format": "(650) 555-0132",
"intl_format": "+1 650-555-0132",
"e164_format": "+16505550132",
"rfc3966_format": "tel:+1-650-555-0132",
"country_code": "US",
"line_type": "MOBILE",
"carrier": "AT&T",
"region": {
"name": "California",
"code": "CA"
},
"timezones": [
"America/Los_Angeles"
]
}
}// 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
5 search credits per row with at least one phone number.
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)
Crie uma operação em massa enviando emails, domínios ou URLs do LinkedIn e depois inicie a operação. A API encontra os telefones de cada contato de forma assíncrona.
Você pode processar até 10.000 buscas por operação em massa. Para conjuntos maiores, crie várias operações em massa.
Você pode encontrar telefones a partir de endereços de email, domínios de empresas ou URLs de perfis do LinkedIn. Informe um tipo por busca.
Cada resultado inclui o telefone em vários formatos (local, internacional, E164), código do país, tipo de linha (celular, fixo, VoIP), operadora e fuso horário.
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.
Cada busca que retorna um telefone conta como 1 requisição. Buscas sem telefone encontrado não são descontadas da sua cota.
Sim. Configure uma URL de webhook para receber uma notificação quando a sua operação do Buscador de telefone em massa terminar, com os resultados prontos para download.
A API do Buscador de telefone fornece dados de telefone de mais de 100 países, com a formatação internacional correta.
Sim. Depois de uma execução do Buscador de telefone em massa, envie os resultados ao Validador de telefone em massa para classificar validade, tipo de linha e confiança de alcance.
Remova duplicatas, normalize os domínios e garanta que os perfis e emails sejam válidos e completos. Entradas limpas melhoram as taxas de correspondência e reduzem requisições desperdiçadas.