Home / Phone number validation API
Phone number validation API
Published 2026-10-13
ContactLint checks phone numbers over a simple HTTP API. You send a number and a country. You get back whether the number is valid, whether it is possible, its line type and region where the metadata supports them, and the number in E.164, national, and international formats.
We built it for signup forms, CRM cleanup, and AI agents that need to confirm contact data before they use it.
This page also covers what a check like this cannot do. Better you hear that from us before you build on it.
Get a free phone validation API key. 100 checks per month, no card required. Only need to check one number? Use the free phone number validator.
What the phone check returns
Every number is parsed with libphonenumber metadata. Here is what comes back:
- Valid flag. The number matches known number patterns for its region.
- Possible flag. The number has a length that could work for its region.
- Line type. The kind of line the metadata assigns to the number, returned where the metadata supports it.
- Region. The country or region the number belongs to, where the metadata supports it.
- Formats. The number in E.164, national, and international formats.
Store the E.164 version and you get one consistent format for every number, however the user typed it.
Carrier lookups are not offered today. If they are added, the terms of service will describe them first.
Send a request
The endpoint is POST /v1/phone/validate. Send your key as Authorization: Bearer YOUR_KEY or in an x-api-key header.
Example request
curl -X POST https://contactlint.com/v1/phone/validate \
-H "Authorization: Bearer YOUR_KEY" \
-H "content-type: application/json" \
-d '{"phone":"YOUR_NUMBER","country":"US"}'
The body takes phone and a country, such as US.
The response
You get the valid and possible flags, the line type and region where the metadata supports them, and the three formats. Build against the OpenAPI 3.1 spec at /openapi.json.
What libphonenumber metadata can and cannot tell you
libphonenumber is an open source library for parsing and formatting phone numbers. ContactLint uses libphonenumber-js, released under the MIT license. It works from metadata: the rules for how numbers are built in each region.
That gets you a lot. It also has a hard limit. Metadata knows what a number should look like. It knows nothing about what is happening on the phone network right now.
Can metadata tell you this?
| Question | ContactLint answers it | What it returns | If not, what you need |
|---|---|---|---|
| Is the number formatted correctly for its country? | Yes | Valid flag | |
| Could a number this length exist in that region? | Yes | Possible flag | |
| What region is it from? | Yes | Region, where the metadata supports it | |
| What line type does the metadata assign? | Yes | Line type, where the metadata supports it | |
| What is the clean E.164 version? | Yes | E.164, national, and international formats | |
| Is the number in service right now? | No | A live network lookup | |
| Which carrier holds it today, or was it ported? | No | A live network lookup | |
| Does it belong to the person who typed it? | No | SMS or call verification |
A format check catches typos, missing digits, and wrong country codes. It will not catch a disconnected line. If any phone API calls a number "real" without a network lookup, ask how it knows.
When a metadata check is enough, and when it is not
A metadata check is enough when you want to:
- Stop typos and junk on a signup form before they hit your database.
- Clean a CRM export so every number sits in one format.
- Let an AI agent confirm a number is well formed before it writes it to a record.
- Sort numbers by region or line type.
You need more when you:
- Must know a number is live before you call it.
- Need the current carrier for routing.
- Need proof the user owns the number. For that, send a code by SMS or call.
You can also stack them. Run the format check first, then spend money on a live check or an SMS code only for the numbers that pass.
One key for phone and email
ContactLint is an email and phone validation API, so the same key checks both fields. The email endpoint is POST /v1/email/validate. It looks at:
- Practical RFC syntax.
- MX and A records via DNS-over-HTTPS.
- Disposable domains.
- Role addresses such as admin@ and info@.
- Free mail providers.
It never opens an SMTP connection to the mailbox.
Most signup forms ask for an email and a phone number. One key handles both. GET /v1/usage shows the free checks you have used this month and your credit balance. One check is one API or MCP call to a validation tool, phone or email.
Use it from an AI agent (MCP)
ContactLint runs an MCP server at https://contactlint.com/mcp. Point any MCP client that supports streamable HTTP at that URL and send the header Authorization: Bearer YOUR_KEY.
There are two tools: validate_phone and validate_email. Each tool call uses one check.
That gives your agent a plain rule: confirm the number before you save it, text it, or hand it to a person.
Pricing and limits
Plans
All prices are in USD.
| Plan | Checks | Price |
|---|---|---|
| Free | 100 per month | $0 |
| Credit pack | 5,000 | $9 |
| Credit pack | 25,000 | $35 |
| Credit pack | 100,000 | $99 |
Free checks do not roll over. Credits kick in after the monthly free checks run out, and they do not expire. Unused credits are refundable within 14 days of purchase.
Errors and rate limits
- 401: missing or invalid key.
- 402: free checks used up and no credits.
- 429: more than 60 requests per minute per key.
- 400: bad input.
Data sources and privacy
- Phone parsing uses libphonenumber-js (MIT).
- Disposable email domains come from the disposable-email-domains project (CC0 1.0).
- DNS lookups use Cloudflare DNS-over-HTTPS.
We do not store the emails or phone numbers you check. They are processed only to return a result. For each check, we record which key made it, whether it was a phone or email check, whether it used a free check or a credit, and the time.
See the privacy policy for how request data is handled. Use of the API is covered by our terms of service.
Questions: support@contactlint.com
FAQ
Does ContactLint check if a phone number is active?
No. ContactLint parses the number against libphonenumber metadata. It tells you whether the number is valid or possible, its line type and region where the metadata supports them, and its formatted versions. It does not run a live network lookup, so it cannot confirm the number is in service or who holds it today.
What is the difference between valid and possible?
A possible number has a length that could work for its region. A valid number also matches the known number patterns in libphonenumber metadata for that region. Use possible as a loose check on a form, and valid as the stronger check before you store or dial a number.
How much does the phone validation API cost?
You get 100 free checks per month with no card required. After that you buy credit packs in USD: 5,000 checks for $9, 25,000 for $35, or 100,000 for $99. Each phone validation uses one check, from the API or the MCP tool. Credits do not expire, and unused credits are refundable within 14 days of purchase.
Can I use the same key for email validation?
Yes. One ContactLint key works for both endpoints: POST /v1/phone/validate and POST /v1/email/validate. Free checks and credits are tracked per key, and GET /v1/usage shows both. That means one signup and one balance for checking both fields on a signup form or CRM record.
Can an AI agent validate phone numbers with ContactLint?
Yes. Point any MCP client that supports streamable HTTP at https://contactlint.com/mcp and send your key in the Authorization header as a Bearer token. The server exposes two tools, validate_phone and validate_email. Each tool call uses one check from your free allowance or credits.
What happens if I send too many requests?
ContactLint allows 60 requests per minute per key. Past that, the API returns 429. Other errors are plain too: 401 for a missing or invalid key, 402 when free checks are used up and you have no credits, and 400 for bad input. Back off and retry on 429.
Start checking numbers
Signup is one short form. No email is sent, and your key is shown once on the next page, so save it.
Get a free phone validation API key
100 checks per month, no card required. Already have a key? Send your first number to POST /v1/phone/validate. Just need to check one number right now? Use the free phone number validator.
Get a free API key. 100 checks per month, no card required.