// post /v1/bulk/finder
Bulk Email Finder API
حوّل آلاف تركيبات الأسماء والشركات إلى عناوين بريد مهنية موثّقة عبر مهمة API مجمّعة واحدة.
Names, with a domain or company nameحتى 10,000 صف
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 · الطلب
Email Finder مجمّع هو طلب HTTPS واحد
أرسل المعاملات مع مفتاحك وسرّك. كل SDK وCLI وخادم MCP ينفّذون هذا الاستدعاء نفسه.
- type
- finder
- list | data | file
- Names, with a domain or company name
- launch
- القيمة true تبدأ المهمة فورًا
- webhook_url
- يستقبل حدثًا موقّعًا عند انتهاء المهمة
- rows
- حتى 10,000 لكل مهمة
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 · الاستجابة
ما يُعاد إليك
JSON، متطابقة في كل لغة. الحقول التي لا تعرفها Tomba تكون null، ولا تُخمَّن أبدًا.
GET
/email-finderdata.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
}
}كل صف، كما يعيده GET /email-finder
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 · التكلفة والحدود
تكلفة الاستدعاء
لا يُخصم الاستدعاء إلا وفق الشرط أدناه. تعتمد حدود المعدّل على خطتك.
// التكلفة
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)
أنشئ عملية مجمّعة برفع أزواج الاسم والنطاق، ثم شغّل العملية. يعالج API كل عمليات البحث بشكل غير متزامن. استخدم Webhooks أو الاستعلام الدوري لتعرف متى تكتمل المعالجة، ثم نزّل النتائج.
يمكنك معالجة حتى 10,000 عملية بحث بالاسم والنطاق في كل عملية مجمّعة. لمجموعات البيانات الأكبر، أنشئ عدة عمليات مجمّعة.
ارفع البيانات بأعمدة first_name وlast_name وdomain (موقع الشركة). سيعثر API على عنوان البريد الأكثر ترجيحًا لكل شخص.
يعتمد وقت المعالجة على حجم القائمة وعمليات البحث التي تحتاجها. استعلم عن حالة المهمة أو اضبط Webhook لتُبلَّغ عند انتهائها.
تتضمن كل نتيجة عنوان البريد والاسم الكامل والشركة والمنصب ودرجة الثقة وحالة التحقق والمصادر. يمكن تنزيل النتائج بصيغة CSV أو JSON.
نعم، اضبط رابط webhook لتتلقى إشعارًا عند اكتمال العملية المجمّعة. تتضمن حمولة webhook قيمتي bulk_id والحالة.
استخدم GET /v1/bulk/email-finder/{bulk_id} للتحقق من حالة عمليتك. تشمل قيم الحالة pending وprocessing وcompleted وfailed.
كل بريد يُعثر عليه بنجاح يُحتسب طلبًا واحدًا. عمليات البحث التي لا تعيد نتائج لا تُخصم من حصتك.
استخدم أسماء أولى وأسماء عائلة دقيقة مع النطاق الجذري الصحيح للشركة. البيانات المُدخلة النظيفة تحسّن جودة المطابقة والثقة بشكل كبير.
نعم. بعد اكتمال المهمة المجمّعة، مرّر النتائج عبر Bulk Email Verifier لتقليل خطر الارتداد قبل إطلاق الحملة.