API Reference (v2)

Reference for the previous API version. Base URL: https://api.veriphone.io

This is the previous version of the API. Every /v2 endpoint keeps working and existing integrations need no changes. New integrations should use the current reference, which adds lookup modes and richer response fields.

Authentication

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

Authorization header (recommended): Authorization: Bearer YOUR_API_KEY
Cookie: key=YOUR_API_KEY
Query parameter: ?key=YOUR_API_KEY

Error Responses

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

Code	Type	Meaning
400	`BadRequest` / `MissingParameter`	Invalid or missing input
401	`Unauthorized`	Missing or invalid API key
402	`PaymentRequired`	Insufficient credits
403	`Forbidden`	Account inactive or access denied
404	`NotFound`	Resource not found
500	`InternalServerError`	Server error

GET POST /v2/verify

The primary phone number validation endpoint. Validates a phone number and returns carrier, line type, and formatting data. Each successful call deducts 1 credit.

If the number doesn't start with a country prefix (leading +), it will be checked against default_country. If no default country is provided, one is inferred from the caller's IP address.

Parameters

Name	Type		Description
phone	string	Required	Phone number to verify.
default_country	string	Optional	ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`). Auto-detected from IP if omitted.

Response Fields

Field	Type	Description
status	string	`"success"`, `"error"`, or `"syntax-error"`
phone	string	The phone number as submitted
phone_valid	boolean	Whether the number is valid
phone_type	string	`mobile`, `fixed_line`, `toll_free`, `premium_rate`, `shared_cost`, `voip`, `unknown`
phone_region	string	Geographic region name
country	string	Full country name
country_code	string	ISO 3166-1 alpha-2 code
country_prefix	string	Country dialing prefix
international_number	string	International format
local_number	string	Local format
e164	string	E.164 format
carrier	string	Carrier name

Example Request

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

Success Response 200

{
  "status": "success",
  "phone": "+11234567890",
  "phone_valid": true,
  "phone_type": "mobile",
  "phone_region": "California",
  "country": "United States",
  "country_code": "US",
  "country_prefix": "1",
  "international_number": "+1 123-456-7890",
  "local_number": "(123) 456-7890",
  "e164": "+11234567890",
  "carrier": "T-Mobile USA, Inc."
}

Invalid Number Response

{
  "status": "error",
  "phone": "+00000000",
  "phone_valid": false,
  "phone_type": "",
  "phone_region": "",
  "country": "",
  "country_code": "",
  "country_prefix": "",
  "international_number": "",
  "local_number": "",
  "e164": "",
  "carrier": ""
}

Note

If the input has fewer than 4 digits or more than 20, the API returns status: "syntax-error" and does not count against your credit balance.

GET POST /v2/credits

Returns current credit and usage information for your API key.

Parameters

No additional parameters beyond authentication.

Example Request

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

Response 200

{
  "email": "user@example.com",
  "counter": 1250,
  "active": true,
  "payg": 0,
  "limit": 5000,
  "plan": "FREE",
  "renew": 15,
  "last_reset": "2026-03-01T00:00:00Z"
}

Field	Type	Description
email	string	Account email address
counter	number	Verifications used in the current billing period
active	boolean	Whether the account is active
payg	number	Pay-as-you-go credits remaining
limit	number	Monthly verification limit for the current plan
plan	string	Current plan name
renew	number	Day of month when the counter resets
last_reset	string	Timestamp of when the counter was last reset

GET POST /v2/plan/getPayments

Returns payment history and active subscription details for your account.

Parameters

No additional parameters beyond authentication.

Example Request

curl "https://api.veriphone.io/v2/plan/getPayments" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "status": "success",
  "payments": [
    {
      "product_name": "Veriphone Pro",
      "plan_name": "Monthly",
      "currency": "USD",
      "amount": "29.99",
      "receipt_url": "https://...",
      "event_time": "2026-03-15T10:30:00Z"
    }
  ],
  "subscription": {
    "update_url": "https://...",
    "status": "active",
    "next_bill_date": "2026-04-15",
    "currency": "USD",
    "new_price": "29.99"
  }
}

Note

The subscription object is empty { } if no active subscription exists.