Validate a phone number

Validate a single phone number in real time. Returns format, country, line type, carrier, and a confidence score.

POST /api/v1/validate

Authentication

Bearer token — see Authentication.

Request body

Field Type Required Description
phone string yes Phone number to validate. E.164 (+33612345678) or national (0612345678).
country string optional ISO-3166 alpha-2 country code (FR, US, GB…). Required if phone is not E.164.
level string optional basic (default). hlr will be available later as a paid tier.

Cost

Level Cost Status
basic 1 credit available
hlr 8 credits coming soon (will return 400 level_not_available for now)

Example request

curl https://phonevalidationapi.com/api/v1/validate \
  -H "Authorization: Bearer pvs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phone":"+33612345678"}'

National format with country fallback:

curl https://phonevalidationapi.com/api/v1/validate \
  -H "Authorization: Bearer pvs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phone":"0612345678","country":"FR"}'

Response

{
  "valid": true,
  "confidence": "verified",
  "score": 0.95,
  "reason": "valid",
  "input": "+33612345678",
  "formatted": {
    "e164":          "+33612345678",
    "national":      "06 12 34 56 78",
    "international": "+33 6 12 34 56 78"
  },
  "country":       { "iso2": "FR", "code": 33 },
  "region":        null,
  "line_type":     "mobile",
  "carrier":       "SFR",
  "is_disposable": false,
  "is_possible":   true,
  "level":         "basic",
  "checks": {
    "format":     "pass",
    "disposable": "pass",
    "hlr":        "skipped"
  },
  "diagnostics": {
    "format":      { "parsed": true, "is_possible": true, "is_valid": true },
    "disposable":  { "is_disposable": false, "reason": null, "source": null, "matched_prefix": null },
    "confidence":  { "line_type_baseline": "verified", "carrier_profile": { "matched": true, "applied": false } }
  },
  "credits_remaining": 24
}

Field reference

Field Type Description
valid bool True if format is valid AND confidence is not low.
confidence string verified | likely | uncertain | low | invalid — see confidence.
score float 0–1, derived from confidence label. Use score >= 0.80 for "trusted".
reason string One-word reason code — see reason codes.
input string Echoed input value (useful when batching).
formatted.e164 string Canonical E.164 form (+CCNNNNNNNNNN).
formatted.national string Pretty national format for display.
formatted.international string Pretty international format for display.
country.iso2 string ISO-3166 alpha-2.
country.code int International dialing code (e.g. 33 for France).
line_type string mobile, fixed_line, voip, etc — see line types.
carrier string Carrier name (where libphonenumber has data; null otherwise).
is_disposable bool True if matched our disposable / burner database.
is_possible bool libphonenumber's isPossibleNumber — basic length check passed.
level string The level used for this lookup (basic for now).
checks object Per-step status: pass | fail | skipped.
diagnostics object Detailed reasoning per check (transparency).
credits_remaining int Wallet balance after debit.

Error responses

HTTP 401 — Unauthorized        // missing or invalid API key
HTTP 402 — insufficient_credits {"balance": 0, "credits_needed": 1, "top_up_url": "..."}
HTTP 422 — phone_required      // empty or missing phone field
HTTP 422 — invalid_country     // country must be ISO-3166 alpha-2
HTTP 400 — level_not_available // requested level not yet supported
HTTP 429 — rate_limited        // too many requests per minute

See Errors for the full list.