Forms · Customer records · Contact imports
Phone validation API
Clean numbers.
Ready for your app.
Check a phone number before you store it. Get one consistent number for your records, readable formats for your interface and the type recorded in the numbering plan.
Validation and formatting on every plan.
Try a phone number
Try it
From input to integration
Messy input.
Useful JSON.
Start with an international number or supply a country for local input. Explore each task with its request and complete response.
One number to store. Two formats to show.
Store phone with its country code and no spaces. Use national or international for display. This North American number has an unknown numbering-plan type.
Request
curl "https://api.parseapi.com/phone/+14155552671?deep=true" \
-H "X-API-Key: YOUR_API_KEY"Example response
Store once. Display locally.
Three formats.
One phone number.
Normalize form entries and imported contacts into the same format. Keep the country code in your database and show the readable version that fits your interface.
Normalize phone numbers- phone
- +14155552671Store with the + country code.
- national
- (415) 555-2671Display within the country.
- international
- +1 415 555 2671Display across borders.
Example area-code context
+14155552671
- State
- California · CA
- Timezone
- America/Los_Angeles
Detailed when you need it
Read the context
behind the number.
Add ?deep=true for the recorded state, province and timezone when known. Every ordinary field keeps the same value, with the extra context together in Deep.
Included on paid plans. The location belongs to the numbering plan; it does not track a person or device.
Explore North American area codesAdd form.js to your fields
A familiar field. A consistent phone number.
Accept a phone number in your form and keep its normalized international value in the data you submit. Give national input an explicit country.
Formatting checks the numbering plan. Carrier and live-status lookups are separate.
Try the contact formInclude the script once with your website's domain-restricted public key. Use these bindings in your existing form.
<script src="https://cdn.parseapi.com/v1/form.js"
data-key="parse_public_YOUR_KEY" defer></script>
<label for="form-phone">Phone</label>
<input id="form-phone" name="phone" type="tel" autocomplete="tel"
data-parse="phone" data-parse-country="US">
<input type="hidden" name="phone_international"
data-parse-from="form-phone" data-parse-fill="phone">International phone numbers
Country-aware
from the first call.
Validate lengths and patterns against numbering-plan metadata for 246 countries and regions. National formatting follows the number's country.
A valid format is the first check. Assignment, reachability and ownership need their own checks.
A country hint for local input.
Use +44 20 7183 8750 directly, or send 020 7183 8750 with country=GB. North American ten-digit numbers can be recognized from a known area code.
Unknown line types stay unknown. Missing or ambiguous geography stays null.
Inputs, fields and errorsPhone → Carrier · HLR
One clean number. The next question.
Validate and format the number once. Reuse the returned phone value for a carrier or status lookup only when your application needs that answer.
Validate and save the number
/phone/+14155552671
Fields from the response
{
"phone": "+14155552671",
"valid": true
}Read valid, then store phone in its normalized international form. A valid format does not confirm assignment or reachability.
Use
phoneGet the carrier and line type
/carrier/+14155552671
Pass the same phone value to Carrier when you need network identity or line type, including VoIP.
When valid is true and you want a Carrier lookup
Use
phoneCheck assignment and reachability
/hlr/+14155552671
Pass that phone value to HLR when you need a network status observation. Unknown results stay unknown; delivery is not guaranteed.
When valid is true and you want a Live status lookup
Carrier and HLR have their own lookup units and rates.
Need a phonebook listing? Explore Caller IDUse this in your app
// Run on your server with PARSEAPI_KEY in the environment.
const key = process.env.PARSEAPI_KEY;
if (!key) throw new Error('Set PARSEAPI_KEY on your server.');
const segment = value => encodeURIComponent(value);
const timezonePath = zone => zone.split('/').map(segment).join('/');
async function lookup(path, query = {}) {
const url = new URL(path, 'https://api.parseapi.com');
url.search = new URLSearchParams(query).toString();
const response = await fetch(url, {
headers: { 'X-API-Key': key, 'Parse-Version': '2.0.0' },
signal: AbortSignal.timeout(10000),
});
if (!response.ok) {
const error = await response.json().catch(() => null);
throw new Error(error?.message ?? 'ParseAPI returned HTTP ' + response.status);
}
return response.json();
}
const phone = await lookup('/phone/' + segment('+14155552671'));
// These are separately metered checks. Enable only the ones you need.
const includeCarrier = false;
const includeLiveStatus = false;
const usable = phone.valid === true && typeof phone.phone === 'string' && phone.phone.length > 0;
const [carrier, liveStatus] = await Promise.all([
includeCarrier && usable ? lookup('/carrier/' + segment(phone.phone)) : null,
includeLiveStatus && usable ? lookup('/hlr/' + segment(phone.phone)) : null,
]);
console.log({ phone, carrier, liveStatus });From the first request to your app
One key.
Your language.
Call Phone when a number enters your app. Read valid, save phone and use the returned formats in your interface.
Phone API referenceValidate form fields with Form, or clean a CSV or Excel file with Bulk Phone.
HTTP, SDKs and MCP
Use the same API key across ParseAPI. The reference covers parameters, authentication and error handling.
Before you build.
What does valid mean?
The number matches the supported numbering plan’s lengths and patterns. It does not prove that the number is assigned, active, reachable or owned by a person. Use Live status for network status and a separate verification flow to establish ownership.
Can I send a number without its country code?
Yes. Ten-digit North American numbers can be recognized from a known area code. For other national formats, pass a two-letter country hint, such as ?country=GB for 020 7183 8750. A + country code is the clearest input for international numbers.
Which number should I save?
Save phone as a string. It is the normalized number with a leading + and country code, with no spaces. Use national or international when displaying it. Invalid input returns phone: null.
Why is the type sometimes unknown?
Some numbering plans share prefixes between mobile and landline numbers. Phone leaves those types unknown. The possible values are mobile, landline, toll_free and unknown; invalid numbers return null. Carrier provides network line type, including VoIP.
What does Deep add, and what does it cost?
Add ?deep=true for state, state_name and timezone, when known. State and province come from North American area codes; timezone comes from the numbering plan. Deep requires a paid plan for new accounts and uses the same single API request, with no separate verification charge.
Does the timezone tell me where someone is?
It describes the number’s numbering-plan timezone when one can be identified. It does not locate a person or device. Missing or ambiguous timezone and state details stay null.
Can I validate a form or clean a whole file?
Use the API in your application, or add Phone validation with Form. For CSV and Excel files, Bulk lets you review the selected columns, optional network checks and price before starting.
Phone API pricing
Start with a clean number.
Validation and formatting use one API request on every plan. Optional Deep is included on paid plans. Your monthly allowance is shared across ParseAPI products.
Free
Start with a free API key.
Room to grow
Choose your capacity on Plans.