---
title: "Validate a single phone number for list cleaning"
method: POST
path: "/v1/phone/validate"
tags: ["phone-validate-v1"]
---

# Validate a single phone number for list cleaning

`POST /v1/phone/validate`

## Request

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

Returns line type, current carrier, portability, and DNC status.
Each non-cached lookup is billed at $0.003 and aggregated monthly.

## Request body

- PhoneValidateRequest
  - `force` boolean: When true, bypass the skip-already-validated gate and the 30-day cache — a fresh LRN lookup is made and billed. Default false.
  - `phone` string, required: Phone number (E.164 recommended)

## Response `200`

Validation result

- PhoneValidateResponse
  - `cached` boolean: Result served from cache
  - `carrier` string: Friendly display name for current carrier
  - `carrier_raw` string: Raw SPID carrier string from the lookup provider
  - `city` string: City
  - `cost` number: USD billed for this lookup (0 if cached)
  - `country` string: ISO country code
  - `disposition` string: ok | unreachable | risky | invalid | unknown
  - `line_type` string: mobile | fixed line | voip | other | unknown
  - `on_dnc` boolean: Present on the DNC list
  - `phone` string: Normalized E.164 number
  - `ported` boolean: Number has been ported from original carrier
  - `state` string: State / region
  - `valid` boolean: Number is valid per carrier network

## Other responses

- `400`: Validation error
- `401`: Authentication error
- `402`: Billing not enabled
- `503`: Provider unavailable

---

[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)