Phone Number Validator & Formatter: E.164, Type, Country
Pricing
from $0.30 / 1,000 phone number validateds
Offline phone validator: lists or CSV/JSON/XLSX to E.164, country, type, reason. $0.30 per 1,000. Format check only: no carrier, region or time zone lookup.
inputIndex
Optional
Position among the non-blank numbers you supplied (typed list first, then each file in order). Null on a file-error row.
source
Optional
"list" for typed numbers, "file-N" for the Nth file (the typed list and every file are numbered in the order given).
input
Required
The text exactly as supplied. Null on a file-error row.
valid
Required
True when the number matches a number-plan range of its country; false when not. It does not mean the line is connected. Null on a free row (file problem, oversize cell, refused row): nothing was validated.
possible
Optional
True when the length is possible for the country (a weaker test than valid).
e164
Optional
Normalised E.164 form, for example +442079460958. Present for any text that parsed, valid or not.
international
Optional
International format (Include international format).
national
Optional
National format (Include national format).
rfc3966
Optional
tel: URI (Include RFC 3966).
country
Optional
ISO 3166-1 alpha-2 country or territory the number belongs to, taken from the calling code and number plan. For invalid numbers this may be the default country or empty. There is no region, city, carrier or time-zone lookup.
countryName
Optional
English country name.
callingCode
Optional
Country calling code without +, for example 44.
type
Optional
Number type from the number plan. Only for valid numbers; null when the plan does not say.
extension
Optional
Extension found in the input, kept apart from E.164.
error
Required
Reason when the row is not a valid number. Number reasons: NOT_A_NUMBER (text does not look like a phone number), INVALID_COUNTRY (no country could be determined: add + and the country code, or set a default country), INVALID_COUNTRY_CODE (the calling code does not exist), TOO_SHORT / TOO_LONG / INVALID_LENGTH (the digit count does not fit the country), INVALID_NUMBER (the length fits but no number-plan range matches). Free rows (valid is null, never charged): INPUT_TOO_LARGE (a cell longer than 1,000 characters, not read), ROW_REJECTED (the dataset refused the row, for example because it was too large). File problems (a free row, input is null): FILE_HTTP (the server did not answer 200), FILE_BLOCKED (private, local or otherwise refused address), FILE_PLATFORM (Google, video or social-platform link: upload the file instead), FILE_TOO_LARGE (over 50 MB), FILE_TIMEOUT, FILE_DNS, FILE_NETWORK, FILE_REDIRECTS (more than 5), FILE_INVALID_URL, FILE_DOWNLOAD (could not be downloaded), FILE_NOT_DATA (a web page, PDF, image or other file that is not CSV, JSON or XLSX, for example a Google Sheets or Dropbox share link), FILE_COLUMN_NOT_FOUND, FILE_COLUMN_REQUIRED, FILE_SHEET_NOT_FOUND, FILE_BAD_FILE (damaged or unreadable file), FILE_TOO_LARGE_IN_MEMORY (JSON or XLSX too big for the run's memory), FILE_SKIPPED (not read because five earlier files in the run failed). Null when valid.
errorMessage
Optional
Plain-language explanation of error (or, on a free row, of what was not done).
warning
Optional
Only present on a number read from an Excel cell that holds a number rather than text. EXCEL_NUMERIC_CELL: Excel stores numbers without a leading zero, so one may have been dropped (format the column as Text, or add the country code). EXCEL_PRECISION_LOST: the cell holds more than 15 significant digits, which Excel rounds, so the last digits are not reliable. Absent when the cell was text or its number format restores the leading zeros.
warningMessage
Optional
Plain-language explanation of warning. Only present together with warning.
runId
Optional
Only present on free rows (valid is null): the id of the run that wrote the row. A run that restarts after a platform migration uses it to recognise its own free rows and never charge for them.
