// post /v1/bulk/phone-finder
一括電話番号検索 API
1回の非同期ジョブで、大規模な連絡先データを回線種別と通信事業者のメタデータ付きの使える電話番号に変換します。
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 は1回の HTTPS リクエストです
キーとシークレットとともにパラメーターを送信します。すべての SDK、CLI、MCP サーバーがこれと同じ呼び出しを行います。
- type
- phone-finder
- list | data | file
- Email addresses, LinkedIn URLs or domains
- launch
- true ですぐにジョブを開始
- webhook_url
- ジョブ終了時に署名付きイベントを受信
- rows
- 1ジョブあたり最大 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 URL をアップロードして一括処理を作成し、処理を開始します。API が各連絡先の電話番号を非同期で見つけます。
一括処理1回につき最大10,000件の検索を処理できます。それ以上のデータセットは、複数の一括処理を作成してください。
メールアドレス、企業ドメイン、LinkedIn プロフィール URL から電話番号を検索できます。1回の検索につき1つのタイプを指定してください。
各結果には、複数の形式（国内、国際、E164）の電話番号、国番号、回線種別（携帯、固定、VoIP）、通信事業者の情報、タイムゾーンが含まれます。
処理時間はリストのサイズと必要なルックアップによって異なります。ジョブをポーリングするか、Webhookを設定して完了の通知を受け取ってください。
電話番号が返った検索ごとに1リクエストとしてカウントされます。電話番号が見つからなかった検索はクォータにカウントされません。
はい。Webhook URL を設定すると、一括電話番号検索 の処理が完了し、結果をダウンロードできるようになったときに通知を受け取れます。
電話番号検索 API は、世界100か国以上の電話番号データを、正しい国際形式で提供します。
はい。一括電話番号検索の実行後、結果を一括電話番号検証に送り、有効性、回線種別、到達の信頼度を分類できます。
重複を削除し、ドメインを正規化し、プロフィールやメールの値が正しく完全であることを確認してください。入力がクリーンなほど一致率が上がり、無駄なリクエストが減ります。