API Reference

Authentication

All endpoints accept both GET and POST requests. Pass your API key via one of the following methods (checked in this order):

1. Authorization header (recommended): Authorization: Bearer YOUR_API_KEY
2. Cookie: key=YOUR_API_KEY
3. Query parameter: ?key=YOUR_API_KEY

Lookup Modes

Every verification runs in one of two modes, selected with the optional mode parameter:

Current resolves the number's serving carrier from national portability registries. It does not indicate whether the device is switched on or reachable.

Carrier registries update within hours to days of a porting event, per national regulations.

Current lookups are available for a growing list of countries — see the coverage list. If a current lookup cannot be resolved, you receive the full Static result and are charged only the Static rate: no result, no surcharge.

Error Responses

{
  "status": "error",
  "code": 401,
  "type": "Unauthorized",
  "message": "API key or token required"
}

The primary phone number verification endpoint. Validates a phone number and returns carrier, line type, and formatting data — and, in Current mode, the carrier serving the number right now.

Parameters

Response Fields

Example Request

curl "https://api.veriphone.io/v3/verify?phone=%2B14169670000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response 200

{
  "status": "success",
  "phone": "+14169670000",
  "phone_valid": true,
  "phone_type": "fixed_line",
  "phone_region": "Toronto, ON",
  "country": "Canada",
  "country_code": "CA",
  "country_prefix": "1",
  "international_number": "+1 416-967-0000",
  "local_number": "(416) 967-0000",
  "e164": "+14169670000",
  "carrier": "Bell",
  "mode": "static",
  "timezone": ["America/Toronto"],
  "geographical": true
}

Invalid Number Response

A number that was verified and found not valid returns status: "success" with phone_valid: false and a reason — a definitive, charged result. Input that is not a phone number at all returns status: "error" and is not charged. You are charged if and only if status is success.

{
  "status": "success",
  "phone": "+1 123 456 7890",
  "phone_valid": false,
  "reason": "unrecognized_range",
  ...
}

Current mode returns every Static field unchanged, plus two symmetric pairs that tell the number's full story: the carrier and line type the number was originally assigned to, and the carrier and line type serving it now.

Additional Response Fields

Example Request

curl "https://api.veriphone.io/v3/verify?phone=%2B14169670000&mode=current" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response 200

{
  ...all Static fields...,
  "mode": "current",
  "original_carrier": "Bell",
  "original_line_type": "fixed_line",
  "current_carrier": "Comwave Networks",
  "current_line_type": "fixed_line",
  "current_mccmnc": null,
  "ported": true,
  "carrier_data_source": "registry"
}

When resolution is unavailable

If the current carrier cannot be resolved (uncovered country, registry outage), you still receive the complete Static result with HTTP 200 — and pay only the Static rate of 1 credit.

{
  ...all Static fields...,
  "mode": "current",
  "original_carrier": "Bell",
  "original_line_type": "fixed_line",
  "current_lookup": "unavailable",
  "current_carrier": null,
  "current_mccmnc": null,
  "current_line_type": null,
  "ported": null
}

Precision note for US numbers

For US numbers, current also resolves pooled thousands-blocks that prefix-level data cannot see — so it can be more precise than Static even for numbers that were never ported.

Returns your account's balance and usage, split by lookup mode.

Example Request

curl "https://api.veriphone.io/v3/credits" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "email": "you@example.com",
  "counter": 68590,
  "active": true,
  "payg": 36270,
  "limit": 1000000,
  "plan": "ENTERPRISE",
  "renew": 17,
  "last_reset": { "seconds": 1781654402, "nanos": 0 },
  "usage": {
    "static": { "count": 95, "credits": 95 },
    "current": { "count": 4, "credits": 61 }
  }
}

Public, unauthenticated list of countries where Current lookups are available. Also rendered as a browsable page.

Example Request

curl "https://api.veriphone.io/v3/coverage/current"

Response 200

{
  "countries": [
    { "iso": "AG", "covered": true },
    { "iso": "AR", "covered": true },
    ...
  ],
  "updatedAt": "2026-07-04T04:15:00Z"
}

Previous Versions

The v2 API remains fully supported: every /v2 endpoint keeps working, and its responses gain only additive fields. The v2 reference is preserved for existing integrations. New integrations should use /v3.

Bulk CSV processing is documented separately — see Bulk verification.