Endpoints
Ungrouped Endpoints 5
What is the Phone Number Validator and Formatter API?
Validate, parse and format phone numbers worldwide. Returns validity, line type (mobile, fixed-line, VoIP, toll-free), country and calling code, plus E.164, international, national and RFC3966 formats. Batch validation of up to 100 numbers per call. Fast edge-hosted, ruleset-based validation powered by libphonenumber metadata (not a live carrier/HLR lookup).
Phone Number Validator and Formatter API is available on the JoJ API marketplace. Subscribe with a single JoJ API key, call it through one gateway, and pay from one wallet — no separate account or contract with the provider.
Phone Number Validator and Formatter API endpoints
- GET
/validateValidate & format a single phone number
Returns validity, possibility, line type, country, calling code and all four formats. Invalid numbers still return HTTP 200 with valid:false and a reason.
- POST
/validate/batchValidate an array of phone numbers
Validate up to 100 numbers in one request. Returns a per-number result array in the same order.
- GET
/exampleGet an example number for a region
Returns a valid example (mobile) number for the requested country, fully validated and formatted.
- GET
/calling-codeLook up a country calling code
Returns the country calling code (e.g. 49 for DE) for an ISO 3166-1 alpha-2 country code. Returns 422 for an unknown or missing country.
- GET
/regionsList supported regions and calling codes
Lists every supported ISO 3166-1 alpha-2 region together with its country calling code. Useful for building country pickers and for checking coverage.
Frequently asked questions about Phone Number Validator and Formatter API
Does the API check whether a phone number is actually in service?
No. Validation is ruleset-based: it checks that a number is well-formed and assigned under the national numbering plan (libphonenumber metadata). It does not perform live carrier, HLR or number-portability lookups, so it cannot tell whether a line is currently active.
Which formats can I send numbers in?
Send numbers in E.164 form with a leading + (e.g. +4915123456789), or in national form (e.g. 01512 3456789) together with the country query parameter as an ISO 3166-1 alpha-2 code such as DE or US. Spaces, dashes and parentheses are tolerated.
What does the response contain?
Each result includes valid and possible flags, the detected line type (MOBILE, FIXED_LINE, TOLL_FREE, VOIP, ...), the ISO country code, the country calling code, and four formatted variants: e164, international, national and rfc3966. Invalid numbers include a reason such as TOO_SHORT or NOT_A_NUMBER.
How many numbers can I validate in one batch request?
POST /validate/batch accepts up to 100 numbers per call. Results are returned in the same order as the input. Each batch request counts as one API call against your plan.
Why do invalid numbers return HTTP 200?
An invalid number is a normal, expected result, not an error, so the API returns 200 with valid:false and a reason. HTTP 4xx codes are reserved for malformed requests: a missing number parameter, a batch larger than 100 items, or a JSON body that cannot be parsed.
Which countries are supported?
All regions with an ITU-assigned country calling code, currently more than 240. Call GET /regions to retrieve the full list of supported ISO country codes and their calling codes.
How up to date is the numbering data?
The API uses libphonenumber metadata, the same rules used by Android and many telecom applications. The data set is updated regularly as national numbering plans change.
What is the difference between valid and possible?
possible means the number has a plausible length for its country; valid additionally means it matches the national numbering-plan pattern for an assigned range. A number can be possible but not valid (for example, a correct length in an unassigned prefix).