// post /v1/bulk/phone-finder
Bulk Phone Finder API
حوّل مجموعات بيانات جهات الاتصال الكبيرة إلى أرقام هاتف قابلة للاستخدام مع نوع الخط وبيانات المشغّل في مهمة واحدة غير متزامنة.
Email addresses, LinkedIn URLs or domainsحتى 10,000 صف
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 · الطلب
Phone Finder مجمّع هو طلب HTTPS واحد
أرسل المعاملات مع مفتاحك وسرّك. كل SDK وCLI وخادم MCP ينفّذون هذا الاستدعاء نفسه.
- type
- phone-finder
- list | data | file
- Email addresses, LinkedIn URLs or domains
- launch
- القيمة true تبدأ المهمة فورًا
- webhook_url
- يستقبل حدثًا موقّعًا عند انتهاء المهمة
- rows
- حتى 10,000 لكل مهمة
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 · الاستجابة
ما يُعاد إليك
JSON، متطابقة في كل لغة. الحقول التي لا تعرفها Tomba تكون null، ولا تُخمَّن أبدًا.
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
}
}كل صف، كما يعيده 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 · التكلفة والحدود
تكلفة الاستدعاء
لا يُخصم الاستدعاء إلا وفق الشرط أدناه. تعتمد حدود المعدّل على خطتك.
// التكلفة
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)
أنشئ عملية مجمّعة برفع عناوين بريد أو نطاقات أو روابط LinkedIn، ثم شغّل العملية. يعثر API على أرقام الهاتف لكل جهة اتصال بشكل غير متزامن.
يمكنك معالجة حتى 10,000 عملية بحث في كل عملية مجمّعة. لمجموعات البيانات الأكبر، أنشئ عدة عمليات مجمّعة.
يمكنك العثور على أرقام الهاتف باستخدام عناوين البريد أو نطاقات الشركات أو روابط ملفات LinkedIn. قدّم نوعًا واحدًا في كل عملية بحث.
تتضمن كل نتيجة رقم الهاتف بصيغ متعددة (محلية، دولية، E164)، ورمز الدولة، ونوع الخط (جوال، أرضي، VoIP)، ومعلومات المشغّل، والمنطقة الزمنية.
يعتمد وقت المعالجة على حجم القائمة وعمليات البحث التي تحتاجها. استعلم عن حالة المهمة أو اضبط Webhook لتُبلَّغ عند انتهائها.
كل عملية بحث تعيد رقم هاتف تُحتسب طلبًا واحدًا. عمليات البحث التي لا يُعثر فيها على رقم لا تُخصم من حصتك.
نعم، اضبط رابط webhook لتتلقى إشعارًا عند اكتمال عملية البحث المجمّع عن الهواتف وجاهزية النتائج للتنزيل.
يوفر Phone Finder API بيانات الهاتف لأكثر من 100 دولة حول العالم بتنسيق دولي صحيح.
نعم. بعد تشغيل البحث المجمّع عن الهواتف، أرسل النتائج إلى Bulk Phone Validator لتصنيف الصلاحية ونوع الخط والثقة في إمكانية الوصول.
احذف التكرارات، ووحّد النطاقات، وتأكد من أن قيم الملفات والبريد صالحة وكاملة. المدخلات النظيفة تحسّن معدلات المطابقة وتقلل الطلبات المهدرة.