// post /v1/bulk/phone-validator
Bulk Phone Validator API
Validate and normalize high-volume phone datasets in one asynchronous API operation built for scale.
Phone numbers, with an optional countryFino a 10,000 righe
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 · richiesta
Bulk Phone Validator è una sola richiesta HTTPS
Invia i parametri con la tua chiave e il tuo secret. Ogni SDK, la CLI e il server MCP fanno questa stessa chiamata.
- type
- phone-validator
- list | data | file
- Phone numbers, with an optional country
- launch
- true avvia subito il job
- webhook_url
- Riceve un evento firmato quando il job termina
- rows
- Fino a 10,000 per job
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 · risposta
Cosa ricevi
JSON, uguale in ogni linguaggio. I campi che Tomba non conosce sono null, mai indovinati.
GET
/phone-validatorCampodataobject | 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
}
}Ogni riga, come la restituisce 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 · costi e limiti
Quanto costa una chiamata
Una chiamata viene addebitata solo alla condizione indicata sotto. I limiti di frequenza dipendono dal tuo piano.
// costo
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)
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.
You can validate up to 10,000 phone numbers per bulk operation. For larger lists, create multiple bulk operations.
Each phone number is validated for format correctness, country pattern matching, carrier identification, line type detection (mobile, landline, VoIP), and number structure.
Each result includes valid status, phone number in multiple formats (local, international, E164, RFC3966), country code, line type, carrier information, and timezone.
Validation is fast - typical processing is 500-1000 phones per minute. A batch of 10,000 phone numbers typically completes within 2-3 hours.
The API accepts numbers in various formats including local, international with +, E.164, and more. Country detection is automatic.
Yes, configure a webhook URL to receive a notification when your bulk phone validation completes with results ready for download.
Once processing completes, use the download endpoint to get all validation results as CSV or JSON format.
Yes. Bulk validation helps suppress malformed or risky numbers before campaign launch, reducing waste and improving contact quality.
Run validation on import, normalize to E.164, filter by line type or country rules, and re-validate stale lists periodically.