Phone validation

Validates numbers against the international numbering plan (the same metadata that powers Google's libphonenumber): syntax, assigned-range validity, country, formatting, and line type. 1 credit per lookup.

Request

POST /api/v1/validate/phone
Authorization: Bearer vk_live_...
Content-Type: application/json

{"phone": "+14155552671"}

// national format? pass a country hint:
{"phone": "0412 345 678", "country": "AU"}

E.164 input (+1...) needs no hints. For national formats, pass countryas an ISO alpha-2 code or parsing will fail by design — we won't guess a country.

Response

{
  "success": true,
  "result": {
    "type": "phone",
    "input": "+14155552671",
    "valid": true,
    "normalized": {
      "e164": "+14155552671",
      "international": "+1 415 555 2671",
      "national": "(415) 555-2671",
      "country": "US",
      "country_calling_code": "1"
    },
    "line_type": "mobile_or_landline",
    "carrier": null,
    "carrier_source": "none",
    "confidence": "medium",
    "checks": { "syntax": "pass", "possible": "pass", "carrier_lookup": "skipped" },
    "notes": ["This numbering range is shared between mobile and landline in this country; ..."]
  },
  "credits": { "used": 1, "remaining": 499 }
}

Field guide

valid	The number is valid for its region — correct length and an assigned numbering range.
normalized.e164	Canonical +<country><number> form. Store this, not the raw input.
normalized.country	ISO 3166-1 alpha-2 country derived from the numbering plan.
line_type	mobile \| landline \| mobile_or_landline \| voip \| toll_free \| premium_rate \| shared_cost \| personal \| pager \| uan \| voicemail \| unknown.
carrier	Carrier name when carrier enrichment is enabled on the deployment; otherwise null with carrier_source "none".
confidence	high \| medium \| low. Drops to medium when line type comes from a shared numbering range.
notes	Plain-English caveats. Always read these before trusting an edge case.

Honest limitations

Line type is numbering-plan-based.In countries like the US where ranges are shared, you'll get mobile_or_landline with confidence: "medium" rather than a guess. Carrier-level lookups (which resolve this and detect number porting) are an optional enrichment — when active, carrier_source tells you where the answer came from.
Valid ≠ reachable. A valid number can still be switched off or unassigned. Validation filters out typos and fake input; it does not ping the handset.

Try it

Live request against the real engine — no signup needed. Rate-limited; sign up for 500 free credits.