Phone Validation (v1)
Validate Phone Numbers (Batch)
Validate up to 500 phone numbers in a single request for list cleaning.
POST
Validate a batch of phone numbers in one request. Per-number errors (bad format, provider failure, rate-limit timeout) are returned in-band — a single bad phone never fails the whole batch. Results are returned in submission order so you can zip them back into your original list. Same data source, pricing, and caching asDocumentation Index
Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
Use this file to discover all available pages before exploring further.
POST /v1/phone/validate: LRN + internal DNC, $0.003 per non-cached lookup, permanent per-account cache.
Pricing & Billing
Each non-cached number in the batch is billed at $0.003. Once a phone has been validated for your account, repeat lookups are free indefinitely (cost: 0) — pass force=true at the request level (single top-level boolean, applies to every phone in the batch) to bypass the cache and re-validate at $0.003 per number (rare; LRN data only changes on carrier porting). Charges accrue throughout the month and are rolled into a single Stripe charge on the 1st of the following month.
Your account must have an active payment method. Requests from accounts with payment_failed or suspended billing status return 402 Payment Required.
Size Limit
Up to 500 phones per request. This matches our LRN provider’s rate ceiling (50 req/s) — 500 cache-miss numbers take roughly 10 seconds worst-case. For larger lists, chunk client-side or fire multiple requests in parallel. The permanent per-account cache makes re-validation of the same numbers effectively free after the first pass.Request
Array of phone numbers to validate. E.164 format recommended (e.g.,
+14155551234). Common US formats are normalized automatically. Duplicate numbers within a batch are deduplicated by the cache layer — each unique E.164 is only paid once per account, ever.Request-level flag — applies to every phone in the batch. Bypasses the per-account cache and runs a fresh paid lookup for each number. Defaults to
false. Must be a strict boolean — string "true" is rejected with invalid_force.Response
Per-number result in submission order. Each entry is either a successful validation (same schema as the single-number endpoint) or an inline error object with
phone, error, code, and message fields.Aggregated counts and total cost for the batch.
Error Codes
| Code | HTTP | Description |
|---|---|---|
missing_phones | 400 | phones array missing or empty |
invalid_force | 400 | force is not a strict boolean (string "true" / int 1 are rejected) |
too_many_phones | 413 | More than 500 phones in one request |
missing_api_key | 401 | No X-Api-Key header present |
invalid_api_key | 401 | API key revoked or unknown |
no_billing_config | 402 | Account has no billing configuration |
no_payment_method | 402 | No Stripe customer / card on file |
payment_failed | 402 | Most recent charge failed |
suspended | 402 | Account is suspended |
Per-number inline error codes
These appear insideresults[], not at the top level:
| Code | Description |
|---|---|
invalid_phone | The number could not be parsed as E.164 |
provider_error | Upstream lookup failed for this specific number |
rate_limited | Batch hit our LRN provider safety ceiling; retry this subset later |
Behavior Notes
Rate limiting. We self-cap provider calls at 50/s globally across all requests. Beyond that, we honor the provider’s own
x-ratelimit-* headers and back off on 429. For very large cleans, stagger parallel requests or rely on the per-account cache to absorb most of the load after the first pass.