How does the Bulk Phone Validator API work?

Create a bulk operation by uploading phone numbers, then launch the operation. The API validates each phone number asynchronously with format, carrier, and line type checks.

What is the maximum batch size?

You can validate up to 10,000 phone numbers per bulk operation. For larger lists, create multiple bulk operations.

What validation checks are performed?

Each phone number is validated for format correctness, country pattern matching, carrier identification, line type detection (mobile, landline, VoIP), and number structure.

What results are returned?

Each result includes valid status, phone number in multiple formats (local, international, E164, RFC3966), country code, line type, carrier information, and timezone.

How long does processing take?

Validation is fast - typical processing is 500-1000 phones per minute. A batch of 10,000 phone numbers typically completes within 2-3 hours.

What phone number formats are accepted?

The API accepts numbers in various formats including local, international with +, E.164, and more. Country detection is automatic.

Are webhooks supported?

Yes, configure a webhook URL to receive a notification when your bulk phone validation completes with results ready for download.

How do I download results?

Once processing completes, use the download endpoint to get all validation results as CSV or JSON format.

Can I use this before SMS or call campaigns?

Yes. Bulk validation helps suppress malformed or risky numbers before campaign launch, reducing waste and improving contact quality.

What is a recommended validation workflow?

Run validation on import, normalize to E.164, filter by line type or country rules, and re-validate stale lists periodically.

// post /v1/bulk/phone-validator

Bulk Phone Validator API

Validate and normalize high-volume phone datasets in one asynchronous API operation built for scale.

無料 API キーを取得 API リファレンス

Phone numbers, with an optional country最大 10,000 行

POST /bulk/phone-validator

curl -X POST "https://api.tomba.io/v1/bulk/phone-validator" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Phone Validator job","list":"+16505550132","launch":true,"webhook_url":"https://hooks.example.com/tomba"}'

const res = await fetch("https://api.tomba.io/v1/bulk/phone-validator", {
  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 Validator job",
    "list": "+16505550132",
    "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-validator",
    headers={
        "X-Tomba-Key": os.environ["TOMBA_API_KEY"],
        "X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
    },
    json={
      "name": "Phone Validator job",
      "list": "+16505550132",
      "launch": True,
      "webhook_url": "https://hooks.example.com/tomba"
    },
)
job_id = res.json()["data"]["id"]

// 01 · リクエスト

一括Phone Validator は1回の HTTPS リクエストです

キーとシークレットとともにパラメーターを送信します。すべての SDK、CLI、MCP サーバーがこれと同じ呼び出しを行います。

type: phone-validator
list | data | file: Phone numbers, with an optional country
launch: true ですぐにジョブを開始
webhook_url: ジョブ終了時に署名付きイベントを受信
rows: 1ジョブあたり最大 10,000 行

POST /bulk/phone-validator

curl -X POST "https://api.tomba.io/v1/bulk/phone-validator" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Phone Validator job","list":"+16505550132","launch":true,"webhook_url":"https://hooks.example.com/tomba"}'

const res = await fetch("https://api.tomba.io/v1/bulk/phone-validator", {
  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 Validator job",
    "list": "+16505550132",
    "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-validator",
    headers={
        "X-Tomba-Key": os.environ["TOMBA_API_KEY"],
        "X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
    },
    json={
      "name": "Phone Validator job",
      "list": "+16505550132",
      "launch": True,
      "webhook_url": "https://hooks.example.com/tomba"
    },
)
job_id = res.json()["data"]["id"]

// 02 · レスポンス

返される内容

どの言語でも同じ JSON です。Tomba が把握していないフィールドは null となり、推測はしません。

GET/phone-validatorフィールド

dataobject | array: The number's details; an empty array, with phone repeating your input, when it isn't valid
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-validator

201 Created

{
  "data": {
    "id": 1042
  }
}

各行は GET /phone-validator が返す形式です

200 OK

{
  "data": {
    "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 · 料金と制限

呼び出しの料金

呼び出しは以下の条件の場合にのみ課金されます。レート制限はプランによって異なります。

// 料金

1 search credit per valid 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)

// faq

Frequently Asked Questions

ほかにご質問がありますか？ヘルプセンターを見る

1分で最初の呼び出しを

無料アカウント、本物の API キー、Enterprise のお客様と同じエンドポイント。

1無料アカウントを作成月25回の検索。カード不要。

2キーとシークレットをコピーダッシュボードの「API キー」から。

3API を呼び出すリクエストを貼り付けると、JSON で応答が返ります。

const res = await fetch("https://api.tomba.io/v1/email-finder?domain=piedpiper.com&first_name=Richard&last_name=Hendricks", { headers: { "X-Tomba-Key": process.env.TOMBA_API_KEY, "X-Tomba-Secret": process.env.TOMBA_SECRET_KEY } }); const { data } = await res.json();

import os, requests res = requests.get( "https://api.tomba.io/v1/email-finder?domain=piedpiper.com&first_name=Richard&last_name=Hendricks", headers={ "X-Tomba-Key": os.environ["TOMBA_API_KEY"], "X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"], }, ) data = res.json()["data"]

{ "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": [] } }

Bulk Phone Validator API

一括Phone Validator は1回の HTTPS リクエストです

返される内容

呼び出しの料金

関連エンドポイント

Frequently Asked Questions

1分で最初の呼び出しを