# SmartPhoneValidator: full reference

> SmartPhoneValidator validates phone numbers and returns validity, line type, carrier, location, timezone, E.164 format and a 0-100 risk score. Use it in the browser, with a bulk CSV upload, or through a REST API. Coverage is 248+ countries, with US and Canadian numbers a core focus.

Website: https://smartphonevalidator.com/
Short index: https://smartphonevalidator.com/llms.txt
Support: support@smartphonevalidator.com. Sales and partnerships: info@smartphonevalidator.com.

## Quick start

1. Create a free account at https://smartphonevalidator.com/signup. New accounts get 100 free lookups, with no credit card needed.
2. Copy your API key from "API keys" in the dashboard.
3. Send a request to `POST https://api.smartphonevalidator.com/v1/validate`.

```
curl -X POST https://api.smartphonevalidator.com/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"phone": "+1 212 555 1234"}'
```

## Authentication

Send the API key with every request, in either header:

```
X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
```

Keep the key secret. Call the API from a server, never from browser or mobile app code. If a key leaks, rotate it in the dashboard.

## Validate one number

`POST https://api.smartphonevalidator.com/v1/validate`

Request body (JSON):

| Field | Type | Required | Description |
|---|---|---|---|
| phone | string | Yes | The number to check. Any common format works, for example +1 212 555 1234, (212) 555-1234 or 00442079460018. |
| defaultCountry | string | No | Two-letter country code (for example GB) used when the number has no + country code. |

Example response (200 OK):

```
{
  "success": true,
  "data": {
    "isValid": true,
    "e164": "+12125551234",
    "countryCode": "US",
    "countryName": "United States",
    "dialCode": "+1",
    "flag": "🇺🇸",
    "location": "New York, NY",
    "timezone": "America/New_York",
    "lineType": "mobile",
    "carrier": "T-Mobile USA, Inc.",
    "isDisposable": false,
    "riskScore": 4,
    "riskFlags": [],
    "latencyMs": 142,
    "invalidReason": null
  },
  "meta": { "balance": "$24.997", "freeLookups": 0 }
}
```

## Response fields

Fields inside `data`. A field is `null` when the information is not available for that number.

| Field | Type | Description |
|---|---|---|
| isValid | boolean | true if the number is real and correctly formed for its country. |
| e164 | string | The number in E.164 format, for example +12125551234. Best format to store. |
| countryCode | string | Two-letter country code, for example US. |
| countryName | string | Country name. |
| dialCode | string | International dial code, for example +1. |
| flag | string | Country flag emoji. |
| location | string or null | City or area the number was issued in, when available. |
| timezone | string | Timezone for the number, for example America/New_York. |
| lineType | string or null | mobile, landline, voip, toll-free or premium. |
| carrier | string or null | Network the number belongs to, when available. |
| isDisposable | boolean | true if the number looks like a temporary or throwaway number. |
| riskScore | number | 0 to 100. Lower is safer. |
| riskFlags | string[] | Reasons that raised the score. Empty when nothing was found. |
| latencyMs | number | How long the check took, in milliseconds. |
| invalidReason | string or null | Why the number is invalid, in plain English. null for valid numbers. |

`meta.balance` is the remaining wallet balance and `meta.freeLookups` the remaining free lookups.

## Risk score and flags

The risk score runs from 0 to 100. Lower is better: 0 means no warning signs were found. It is different from "valid": a number can be valid and still have a high risk score.

| Score | Band | What to do |
|---|---|---|
| 0-24 | Low risk | Looks like a normal, real phone number. Safe to contact or accept. |
| 25-49 | Medium risk | Something looks unusual. Worth a second check, such as an OTP or a quick review. |
| 50-100 | High risk | Several warning signs. Verify before you trust it, or block it if your use case is strict. |

Common values in `riskFlags` (treat the list as open-ended and handle unknown values gracefully):

- voip: internet-based (VoIP) number
- disposable_number: temporary or throwaway number
- toll_free: toll-free business number
- premium_rate: premium-rate number that charges the caller
- repeated_digits: digits like 1111111111
- sequential_digits: digits like 1234567890
- pattern_digits: other made-up looking patterns
- short_number: unusually short for its country
- unknown_carrier: no carrier could be found
- high_risk_country: country with high fraud rates

Guide: https://smartphonevalidator.com/risk-score/

## Batch: up to 100 numbers

`POST https://api.smartphonevalidator.com/v1/validate/batch`

Send a `phones` array of up to 100 numbers. Results come back in the same order, with the same fields as a single lookup.

```
curl -X POST https://api.smartphonevalidator.com/v1/validate/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"phones": ["+14155552671", "+447911123456"]}'
```

The response `meta` includes `count`, `lookupsCharged`, `balance` and `freeLookups`.

## Bulk CSV

For large lists, upload a CSV. It runs in the background and you poll for the result. The file needs a column named phone, number, mobile or tel. You can also upload from the dashboard, and an email is sent when the job is done.

1. Upload: `POST https://api.smartphonevalidator.com/v1/bulk/upload` with the file as multipart form field `file`. Returns 202 Accepted with `jobId` and `pollUrl`.
2. Check status: `GET https://api.smartphonevalidator.com/v1/bulk/JOB_ID`. The response has `status`, `totalRows`, `processed`, `progressPct`, `validCount`, `riskyCount`, `invalidCount` and, when `status` is done, `resultUrl`.
3. Download the results CSV from `resultUrl` or from Bulk history in the dashboard.

```
curl -X POST https://api.smartphonevalidator.com/v1/bulk/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@contacts.csv"
```

## Pricing and billing

- $0.004 per phone number checked, whatever the result. The same price applies to single lookups, batch calls and bulk CSV uploads.
- Prepaid wallet. No plans, no subscriptions, and the balance never expires. Free lookups are used first, then the wallet.
- Every new account gets 100 free lookups, with no credit card required.
- Add $10 to $5,000 per payment. Card payments are processed by Stripe; card details are never stored by SmartPhoneValidator.
- Optional automatic refill: choose a low-balance level and an amount, and the saved card is charged when the wallet falls below that level. A daily refill limit can be set, and refill can be turned off at any time.
- A batch or bulk job needs enough funds for every number before it starts. If not, the API returns 402 and nothing is charged.
- In live lookup, checking the same number again within 7 days is free. In bulk, a number that appears more than once in the same file is charged once.
- Payments are non-refundable (see the Terms). Very large volumes: contact sales for volume pricing and invoicing.

Pricing page: https://smartphonevalidator.com/pricing/

## Errors

Errors return `success: false` with a human-readable `message`.

```
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your wallet is empty. Add funds to continue."
  }
}
```

| HTTP | Meaning |
|---|---|
| 400 | The request is missing a field or is malformed, for example no phone, or more than 100 numbers in a batch. |
| 401 | Missing or invalid API key. |
| 402 | Not enough funds. Add funds to the wallet from the dashboard. |
| 422 | The uploaded CSV could not be read or has no phone column. |
| 500 | Something went wrong on our side. Retry, and contact support if it continues. |

## What a result does and does not tell you

- A valid number is correctly formed and exists. It does not prove who owns the number. Use a separate ownership verification step (such as an OTP) when you need that.
- Validation does not guarantee that an SMS will arrive. Channel support and network conditions still affect delivery.
- Carrier and location come from numbering data and can be missing or out of date for some numbers, especially ported ones. Location is regional context, not device tracking.

## Free tools

- Phone Validator: https://smartphonevalidator.com/tools/phone-validator/ (validate a phone number in real time)
- Line Type Checker: https://smartphonevalidator.com/tools/line-type-checker/ (mobile, landline, VoIP or toll-free)
- Carrier Lookup: https://smartphonevalidator.com/tools/carrier-lookup/ (carrier and network)
- Number Format Checker: https://smartphonevalidator.com/tools/number-format-checker/ (format and E.164)
- Location Finder: https://smartphonevalidator.com/tools/location-finder/ (country, region, city, timezone)
- Bulk Validator: https://smartphonevalidator.com/tools/bulk-validator/ (CSV upload and download)

## Use cases

Lead capture forms, user registration and sign-up checks, SMS and voice campaigns (for example, removing landlines from an SMS list), CRM and database clean-up, and fraud or risk review using line type and the risk score. Details: https://smartphonevalidator.com/use-cases/

## Coverage

248+ countries and territories are supported. 222 of them have their own page listing the dial code and an example number, for example https://smartphonevalidator.com/coverage/united-states/. Index: https://smartphonevalidator.com/coverage/

## Page guide

Every page, with what it is for. All addresses start with https://smartphonevalidator.com.

- Home (/): real-time phone number validation API. Line type, carrier, location and risk score for the US, Canada and 248+ countries, with a live number checker.
- Features (/features/): what a phone lookup returns and how to read it: validation status (Valid, Risky, Invalid), line type, carrier, E.164 format, country and timezone, and risk signals. Includes four product screenshots.
- Use cases (/use-cases/): lead capture, user registration, SMS and voice campaigns, CRM clean-up and risk review.
- Risk score (/risk-score/): the 0–100 score explained. 0–24 low, 25–49 medium, 50–100 high; what raises it and what to do with it.
- Pricing (/pricing/): $0.004 per validation from a prepaid wallet ($10–$5,000 per payment), optional automatic refill, 100 free lookups for new accounts, no subscriptions.
- API documentation (/docs/): authentication, POST /v1/validate, batch (up to 100 numbers), bulk CSV, billing and errors.
- Free tools (/tools/): Phone Validator, Line Type Checker, Carrier Lookup, Number Format Checker, Location Finder and Bulk Validator, each on its own page.
- Country coverage (/coverage/): one page per country or territory (248+), for example /coverage/united-states/ and /coverage/canada/.
- Contact (/contact/): sales and partnerships, technical support, book a demo.
- Terms (/terms/), Privacy (/privacy/) and Refund policy (/refund-policy/).
- Site map (/site-map/): every section in one page, with the product screenshots.

## Images

All product screenshots are real screens of the SmartPhoneValidator web app, taken with sample data (a fictional account and fictional 555 phone numbers). Each is a WebP file at two sizes: replace `-1800` with `-900` in the address for the smaller one. They appear on https://smartphonevalidator.com/features/ and https://smartphonevalidator.com/site-map/.

1. Live lookup. https://smartphonevalidator.com/images/product/live-lookup-result-1800.webp
   The dashboard "Live lookup" screen. On the left: a phone number field with the US flag and +1, and a Check button. Below it a result card for +1 212-555-1234 marked "Valid", "Mobile · T-Mobile USA, Inc. · United States", with a risk bar showing 4, Low. A table lists Status Valid, Country US — United States, Location New York, NY, Region NY, Timezone America/New_York (-05:00), Carrier T-Mobile USA, Inc., Line type Mobile, Risk score 4/100, Risk flags None and E.164 +12125551234. On the right, "Same check via API" shows the matching request (cURL, with Node.js, Python, Java and C# tabs) to POST https://api.smartphonevalidator.com/v1/validate and the 200 OK JSON response with isValid, e164, countryCode, location, timezone, lineType, carrier, riskScore and riskFlags. The left menu lists Overview, Live lookup, Bulk validate, Bulk History, Logs, API keys, Settings, Billing, Payments and Support, and the wallet shows $18.40 at $0.004 per lookup.

2. Bulk validation. https://smartphonevalidator.com/images/product/bulk-history-1800.webp
   The "Bulk History" screen. Totals for the last 7 days: 22,520 numbers processed, 18,537 valid, 902 invalid, 1,331 risky. A list of CSV jobs: newsletter-signups-nov.csv (done, 12,480 numbers: 11,204 valid, 470 invalid, 806 risky, shown as a donut chart of 90% valid, 4% invalid and 6% risky, with uploaded, started and finished times and a 456 s duration), crm-export-q4.csv (done, 5,000 numbers), webinar-leads.csv (done, 1,840 numbers) and trial-users.csv (processing, 1,450 of 3,200, 45%). Each finished job has a Download button. A side panel counts jobs by state and a "Validate a new CSV" button starts a new upload.

3. Overview. https://smartphonevalidator.com/images/product/dashboard-overview-1800.webp
   The dashboard "Overview" screen for the last 30 days: 11,230 numbers checked, of which 9,352 valid, 1,066 risky and 812 invalid. A stacked bar chart "Validation volume" shows numbers checked per day from Oct 14 to Nov 12, split into Valid (green), Risky (amber) and Invalid (red), rising to about 490 a day. A Wallet card shows 62 free lookups left and $18.40 ("Free lookups are used first") with Add funds and Payments buttons. Quick actions link to Live lookup, Bulk validate, API keys and Logs. Below are a result breakdown bar and a line types table.

4. Request logs. https://smartphonevalidator.com/images/product/validation-logs-1800.webp
   The "Request logs" screen: "6 validation calls in the last 90 days", a search box, status filters (All, Valid, Invalid, Risky), a country filter and a date range. A table with the columns Number, Country, Carrier, Type, Status, Risk and Time. Rows include a valid Verizon Wireless mobile number with risk 4, a valid T-Mobile mobile number with risk 4, a Google Voice VoIP number marked Risky with risk 58, a valid Verizon landline with risk 9, a valid AT&T mobile with risk 6, and an Invalid number with no carrier or line type.

5. Share image. https://smartphonevalidator.com/opengraph-image.png
   The social preview card used when a page is shared: the SmartPhoneValidator logo, the headline "Phone validation API for cleaner contact data", the line "Check validity, line type, carrier, location and risk score for US, Canadian and international numbers.", and the badges "100 free lookups" and "$0.004 per lookup".

Image list for crawlers: https://smartphonevalidator.com/sitemap-images.xml

## Pages

- Home: https://smartphonevalidator.com/
- Docs: https://smartphonevalidator.com/docs/
- Features: https://smartphonevalidator.com/features/
- Risk score: https://smartphonevalidator.com/risk-score/
- Use cases: https://smartphonevalidator.com/use-cases/
- Pricing: https://smartphonevalidator.com/pricing/
- Contact: https://smartphonevalidator.com/contact/
- Terms: https://smartphonevalidator.com/terms/
- Privacy: https://smartphonevalidator.com/privacy/
- Refund policy: https://smartphonevalidator.com/refund-policy/
- Sitemap: https://smartphonevalidator.com/sitemap.xml