// post /v1/bulk/phone-finder
API de recherche de téléphone en masse
Résolvez de grands ensembles de données de contacts en numéros de téléphone utilisables avec le type de ligne et les métadonnées de l'opérateur en une seule tâche asynchrone.
Email addresses, LinkedIn URLs or domainsJusqu'à 10,000 lignes
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 · requête
Phone Finder en masse tient en une requête HTTPS
Envoyez les paramètres avec votre clé et votre secret. Chaque SDK, la CLI et le serveur MCP effectuent ce même appel.
- type
- phone-finder
- list | data | file
- Email addresses, LinkedIn URLs or domains
- launch
- true lance la tâche immédiatement
- webhook_url
- Reçoit un événement signé à la fin de la tâche
- rows
- Jusqu'à 10,000 par tâche
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 · réponse
Ce qui est renvoyé
Du JSON, identique dans tous les langages. Les champs que Tomba ne connaît pas valent null, jamais une supposition.
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
}
}Chaque ligne, telle que GET /phone-finder la renvoie
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 · coût et limites
Ce que coûte un appel
Un appel n'est facturé que dans la condition ci-dessous. Les limites de débit dépendent de votre offre.
// coût
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)
Créez une opération groupée en téléchargeant des e-mails, des domaines ou des URL LinkedIn, puis lancez l'opération. L'API recherche les numéros de téléphone de chaque contact de manière asynchrone.
Vous pouvez traiter jusqu’à 10 000 recherches par opération groupée. Pour les ensembles de données plus volumineux, créez plusieurs opérations groupées.
Vous pouvez trouver des numéros de téléphone à l'aide d'adresses e-mail, de domaines d'entreprise ou d'URL de profil LinkedIn. Fournissez un type par recherche.
Chaque résultat comprend le numéro de téléphone dans plusieurs formats (local, international, E164), l'indicatif du pays, le type de ligne (mobile, fixe, VoIP), les informations sur l'opérateur et le fuseau horaire.
Le temps de traitement dépend de la taille de la liste et des recherches nécessaires. Interrogez le statut de la tâche ou configurez un webhook pour être averti de sa fin.
Chaque recherche qui renvoie un numéro de téléphone compte pour 1 requête. Les recherches sans téléphone trouvé ne sont pas comptabilisées dans votre quota.
Oui, configurez une URL de webhook pour recevoir une notification lorsque votre opération de recherche groupée de téléphones se termine avec des résultats prêts à être téléchargés.
L'API Phone Finder fournit des données téléphoniques pour plus de 100 pays dans le monde avec un formatage international approprié.
Oui. Après une exécution groupée de recherche de téléphones, envoyez les résultats à Bulk Phone Validator pour classer la validité, le type de ligne et la fiabilité de la délivrabilité.
Supprimez les doublons, normalisez les domaines et assurez-vous que les valeurs de profil/e-mail sont valides et complètes. Des entrées propres améliorent les taux de correspondance et réduisent les demandes inutiles.