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 (also known as MNP data). 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.