// post /v1/bulk/phone-finder
API Bulk Phone Finder
Trasforma grandi set di contatti in numeri di telefono utilizzabili, con tipo di linea e operatore, in un solo job asincrono.
Email addresses, LinkedIn URLs or domainsFino a 10,000 righe
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 · richiesta
Phone Finder in blocco è 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
- phone-finder
- list | data | file
- Email addresses, LinkedIn URLs or domains
- launch
- true avvia subito il job
- webhook_url
- Riceve un evento firmato quando il job termina
- rows
- Fino a 10,000 per 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 · risposta
Cosa ricevi
JSON, uguale in ogni linguaggio. I campi che Tomba non conosce sono null, mai indovinati.
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
}
}Ogni riga, come la restituisce GET /phone-finder
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 · 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
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)
Crea un'operazione bulk caricando email, domini o URL LinkedIn, poi avviala. L'API trova in modo asincrono i numeri di telefono di ogni contatto.
Puoi elaborare fino a 10.000 ricerche per operazione bulk. Per set di dati più grandi, crea più operazioni bulk.
Puoi trovare numeri di telefono a partire da indirizzi email, domini aziendali o URL di profili LinkedIn. Indica un solo tipo per ricerca.
Ogni risultato include il numero di telefono in più formati (locale, internazionale, E164), prefisso internazionale, tipo di linea (mobile, fissa, VoIP), operatore e fuso orario.
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.
Ogni ricerca che restituisce un numero di telefono conta come 1 richiesta. Le ricerche senza numero non vengono conteggiate nella tua quota.
Sì, configura un URL webhook per ricevere una notifica quando l'operazione di ricerca telefoni in blocco è completata e i risultati sono pronti da scaricare.
L'API Phone Finder fornisce dati telefonici per oltre 100 paesi nel mondo, con la corretta formattazione internazionale.
Sì. Dopo una ricerca telefoni in blocco, invia i risultati a Bulk Phone Validator per classificare validità, tipo di linea e affidabilità.
Rimuovi i duplicati, normalizza i domini e assicurati che profili ed email siano validi e completi. Input puliti migliorano il tasso di corrispondenza e riducono le richieste sprecate.