API Reference

Complete reference for all public Veriphone API endpoints. Base URL: https://api.veriphone.io

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.