---
title: "Validate a batch of phone numbers for list cleaning"
method: POST
path: "/v1/phone/validate/batch"
tags: ["phone-validate-v1"]
---

# Validate a batch of phone numbers for list cleaning

`POST /v1/phone/validate/batch`

## Request

- Base URL: `https://api.tracklysms.com/api`
- URL: `https://api.tracklysms.com/api/v1/phone/validate/batch`
- Auth: API key in header `X-Api-Key`

Per-number errors are returned in-band — a single bad phone never fails
the whole batch. Each non-cached lookup is billed at $0.003 and aggregated
into the account's monthly phone-validation roll-up.

## Request body

- PhoneValidateBatchRequest
  - `force` boolean: When true, bypass the skip-already-validated gate and the 30-day cache for every item in the batch — each is a fresh LRN lookup and billed. Default false.
  - `phones` string[], required: Phone numbers to validate (E.164 recommended). Max 500 per request.

## Response `200`

Batch validation results

- PhoneValidateBatchResponse
  - `results` object[]: Per-number result in submission order. Each item is either a PhoneValidateResponse or a per-number error with phone/error/code/message.
  - `summary` PhoneValidateBatchSummary
    - `cached` integer: Count served from the 30-day cache ($0 billed)
    - `errors` integer: Per-number errors (invalid format, provider failure, rate-limited)
    - `invalid` integer: Count with disposition=invalid
    - `ok` integer: Count with disposition=ok
    - `risky` integer: Count with disposition=risky
    - `total` integer: Total phones submitted
    - `total_cost` number: Sum of USD billed for this request
    - `unknown` integer: Count with disposition=unknown
    - `unreachable` integer: Count with disposition=unreachable

## Other responses

- `400`: Validation error
- `401`: Authentication error
- `402`: Billing not enabled
- `413`: Too many phones

---

[API](https://skmtc.dev/tracklysms/apis/trackly-sms-api.md) · [All operations](https://skmtc.dev/tracklysms/apis/trackly-sms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tracklysms/apis/trackly-sms-api/revisions/ac1ad22cb2a9?raw)