Validate numbers · Ready Docs

#Validate numbers

Check whether numbers are mobile, landline or disconnected before you import or text them. US and Canada only.

Details

This is the same lookup and price as Clean list on the Contacts page.

#Validate numbers

POST/v1/validate

Checks up to 1,000 numbers. Billed per number that gets an answer.

Auth API key with edit_contacts
Idempotent Yes, with Idempotency-Key
Rate limit About 120 requests/min per account
Cost $0.005 per number answered, cached answers included

Important. Checking the same number again, in a later call, is billed again.

Details

A number repeated within one request is looked up and billed once. Malformed numbers and numbers that got no answer aren't billed. The whole batch is checked against your balance first.

Answers are cached for 90 days and shared across Ready accounts, so cached: true can mean another account checked the number.

Example: 100 different numbers that all get an answer cost 100 × $0.005 = $0.50, and the same 100 again cost another $0.50.

Headers

Idempotency-KeystringRecommended: Retry safely without paying twice.

Body parameters

phonesstring[]Required: 1 to 1,000 numbers, E.164 or 10 digits.

Returns

data[]object[]: One per number, in the order you sent them.
data[].normalizedE.164 string | null: null when the number can't be read.
data[].validboolean: false if malformed or disconnected; reason is invalid_format, unsupported_country or disconnected.
data[].line_typeenum: mobile, landline or unknown. A line the carrier lookup reports only as "landline or other carrier", which includes most VoIP lines, reads as unknown: it is still an answer and is billed.
data[].carrierstring | null: The carrier, for mobile numbers.
data[].textableboolean | null: null when line_type is unknown: the lookup gave no answer, or could not tell.
data[].cached, checked_atboolean, ISO 8601 string: Whether the answer was cached, and when it was checked.
billed_numbers, charged_usdinteger, number: At the top level: what this call cost.
Details
charged_usd is exact: $0.005 for each number that got an answer, so one number shows charged_usd: 0.005 and billed_numbers: 1 every time. Your balance is debited in whole cents and the half cent is carried to the next charge. Both are 0 when nothing was charged (for example a test key).

Errors

HTTP	Code	When
400	`phones_required`	`phones` is missing or empty.
400	`too_many_phones`	More than 1,000 numbers.
402	`insufficient_credits`	Balance can't cover the batch. Nothing checked. Details The body has `required_cents`, `balance_cents` and `numbers`.
403	`permission_denied`	Key lacks `edit_contacts`.
429	`validation_in_progress`	Same numbers already being checked. Wait `Retry-After`.
500	`internal_error`	Some may be billed: check your balance first.
503	`validation_unavailable`	Unavailable right now. Nothing charged.

POST /v1/validate

curl -X POST "https://api.tryready.com/v1/validate" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": [
      "+12125550199",
      "+15559876543",
      "+442071234567"
    ]
  }'

const res = await fetch('https://api.tryready.com/v1/validate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "phones": [
      "+12125550199",
      "+15559876543",
      "+442071234567"
    ]
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, uuid, requests

r = requests.post(
    "https://api.tryready.com/v1/validate",
    headers={"X-API-Key": os.environ["READY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    json={
        "phones": ["+12125550199", "+15559876543", "+442071234567"]
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": [
    {
      "phone": "+12125550199",
      "normalized": "+12125550199",
      "valid": true,
      "line_type": "mobile",
      "carrier": "T-Mobile",
      "textable": true,
      "cached": false,
      "checked_at": "2026-10-01T21:30:00.512Z"
    },
    {
      "phone": "+15559876543",
      "normalized": "+15559876543",
      "valid": true,
      "line_type": "landline",
      "carrier": null,
      "textable": false,
      "cached": true,
      "checked_at": "2026-09-28T14:02:11.090Z"
    },
    {
      "phone": "+442071234567",
      "normalized": null,
      "valid": false,
      "reason": "unsupported_country",
      "line_type": "unknown",
      "carrier": null,
      "textable": false,
      "cached": false,
      "checked_at": null
    }
  ],
  "billed_numbers": 2,
  "charged_usd": 0.01
}

#Validate one number

GET/v1/validate/:phone

The same check for one number. This GET is billed like one number above.

Auth API key with edit_contacts
Rate limit About 120 requests/min per account
Cost $0.005 if answered

Path parameters

phonestringRequired: E.164 or 10 digits.
Details
A value that isn't a phone number answers 200 with valid: false, reason: "invalid_format", not billed.

Returns

dataobject: One result like a data[] item above, plus billed_numbers and charged_usd.

Errors

HTTP	Code	When
400	`invalid_phone`	Path value over 40 characters.
402	`insufficient_credits`	Balance too low.
403	`READ_ONLY_SESSION`	View-only access can't spend money.
403	`permission_denied`	Key lacks `edit_contacts`.
429	`validation_in_progress`	This number is already being checked. Wait `Retry-After`.
500	`internal_error`	Our side failed. Retry.
503	`validation_unavailable`	Unavailable right now. Nothing charged.

GET /v1/validate/:phone

curl "https://api.tryready.com/v1/validate/+12125550199" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/validate/+12125550199', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/validate/+12125550199",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "phone": "+12125550199",
    "normalized": "+12125550199",
    "valid": true,
    "line_type": "mobile",
    "carrier": "T-Mobile",
    "textable": true,
    "cached": false,
    "checked_at": "2026-10-01T21:30:00.512Z"
  },
  "billed_numbers": 1,
  "charged_usd": 0.01
}