API DOCUMENTATION

Validate phone numbers with one API call

A simple REST API that returns validity, line type, carrier, location and a risk score for any number.

Quick start

Create a free account. You get 100 free credits, with no card needed.
Copy your API key from API keys in your dashboard.
Send a request to POST /v1/validate, as shown below.

Request

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 your API key with every request, in either header:

Headers

X-API-Key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY

Keep your key secret. Call the API from your server, not from browser code, and rotate the key in your dashboard if it leaks.

Validate a number

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

FieldTypeDescription

phoneRequiredstringThe number to check. Any common format works: +1 212 555 1234, (212) 555-1234, 00442079460018.

defaultCountryOptionalstringTwo-letter country code (e.g. GB) used when the number has no + country code.

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": { "creditsRemaining": 4999 }
}

Response fields

Fields inside data. A field is null when the information isn't available for that number.

FieldTypeDescription

isValidbooleantrue if the number is real and correctly formed for its country.

e164stringThe number in E.164 format, e.g. +12125551234. Best format to store.

countryCodestringTwo-letter country code, e.g. US.

countryNamestringCountry name.

dialCodestringInternational dial code, e.g. +1.

flagstringCountry flag emoji, handy for UIs.

locationstring | nullCity or area the number was issued in, when available.

timezonestringTimezone for the number, e.g. America/New_York.

lineTypestring | nullmobile, landline, voip, toll-free or premium.

carrierstring | nullNetwork the number belongs to, when available.

isDisposablebooleantrue if the number looks like a temporary or throwaway number.

riskScorenumber0–100. Lower is safer. See the Risk Score guide.

riskFlagsstring[]Reasons that raised the score (see below). Empty when nothing was found.

latencyMsnumberHow long the check took, in milliseconds.

invalidReasonstring | nullWhy the number is invalid, in plain English. null for valid numbers.

Risk flags

Common values you may see in riskFlags. Treat the list as open-ended: new flags can be added, so handle unknown values gracefully. For how they affect the score, see the Risk Score guide.

voipInternet-based (VoIP) number

disposable_numberTemporary or throwaway number

toll_freeToll-free business number

premium_ratePremium-rate number that charges the caller

repeated_digitsDigits like 1111111111

sequential_digitsDigits like 1234567890

pattern_digitsOther made-up looking patterns

short_numberUnusually short for its country

unknown_carrierNo carrier could be found

high_risk_countryCountry with high fraud rates

Batch: up to 100 numbers

POST https://api.smartphonevalidator.com/v1/validate/batch. Send a phones array. Results come back in the same order, with the same fields as a single lookup.

Request

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"]}'

Response · 200 OK

{
  "success": true,
  "data": [ { "isValid": true, "e164": "+14155552671", ... },
            { "isValid": true, "e164": "+447911123456", ... } ],
  "meta": { "count": 2, "creditsRemaining": 4997 }
}

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 we email you when the job is done.

1 · Upload

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

Response · 202 Accepted

{
  "success": true,
  "data": { "jobId": "…", "pollUrl": "/v1/bulk/…" }
}

2 · Check status

curl https://api.smartphonevalidator.com/v1/bulk/JOB_ID \
  -H "X-API-Key: YOUR_API_KEY"

Response · 200 OK

{
  "success": true,
  "data": {
    "jobId": "…",
    "status": "done",
    "totalRows": 5000,
    "processed": 5000,
    "progressPct": 100,
    "validCount": 4410,
    "riskyCount": 312,
    "invalidCount": 278,
    "resultUrl": "…"
  }
}

When status is done, download the results CSV from the dashboard (Bulk history) or from resultUrl.

Credits

Each number checked uses 1 credit, whatever the result: single, batch or bulk.
Successful responses include your remaining balance in meta.creditsRemaining.
A batch or bulk job needs enough credits for every number before it starts.
Credits never expire. See Pricing to top up.

Errors

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

Example · 402

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "You have run out of credits. Please upgrade your plan."
  }
}

HTTPMeaning

400The request is missing a field or is malformed, e.g. no phone, or more than 100 numbers in a batch.

401Missing or invalid API key.

402Not enough credits. Top up from your dashboard.

422The uploaded CSV could not be read or has no phone column.

429Too many requests. Wait a moment and retry.

500Something went wrong on our side. Retry, and contact support if it continues.

Stuck? Contact support and include the request you sent, but never your API key.