// 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 countryTot 10,000 rijen
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 · verzoek
Bulk Phone Validator is één HTTPS-verzoek
Stuur de parameters mee met je sleutel en secret. Elke SDK, de CLI en de MCP-server doen precies deze aanroep.
- type
- phone-validator
- list | data | file
- Phone numbers, with an optional country
- launch
- true start de taak meteen
- webhook_url
- Ontvangt een ondertekend event als de taak klaar is
- rows
- Tot 10,000 per taak
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 · antwoord
Wat je terugkrijgt
JSON, in elke taal hetzelfde. Velden die Tomba niet kent zijn null, nooit gegokt.
GET
/phone-validatorVelddataobject | 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
}
}Elke rij, zoals GET /phone-validator die teruggeeft
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 · kosten en limieten
Wat een aanroep kost
Een aanroep wordt alleen in rekening gebracht onder de voorwaarde hieronder. Rate limits hangen af van je abonnement.
// kosten
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.