Phone Number Validation

The phone number validation endpoint provides comprehensive validation and formatting of phone numbers according to international standards. This service validates the structure and format of phone numbers, determines their type (mobile, landline, etc.), and provides various formatting options including E.164 international format. The validation includes checking for valid country codes, number lengths, and area codes according to international numbering plans.

Phone number validation helps ensure data quality by standardizing formats and confirming structural validity. The service supports international phone numbers and provides detailed information about the number's type and country of origin, making it valuable for both domestic and international use cases.

IMPORTANT

This validation performs ONLY number pattern conformity checks against standardized international telephony formats and does not verify the actual existence or operational status of the phone line. A successful validation only confirms that the phone number follows the correct structure for its region (e.g., valid country code, proper length, correct area code format, legitimate number pattern).

A "valid" result should NOT be interpreted as confirmation that the phone number is currently active, connected, or capable of receiving calls or messages. For mission-critical systems requiring guaranteed phone number reachability, additional verification steps such as carrier lookup, line type verification, or direct contact confirmation workflows must be implemented separately.

Model

Specific structure of the data that represents the entity within the API. It defines the attributes and their data types associated with the entity.

It's important to note that you'll need to retrieve the complete identifier for an entity each time you require its complete model. This can be achieved by utilizing the find endpoint to locate the entity and then using the retrieved identifier to call the retrieve endpoint for complete model.

  • Name
    numberRaw
    Type
    string
  • Name
    numberNormalized
    Type
    string
  • Name
    formatted
    Type
    object
    Description
    • Name
      e164
      Type
      string
    • Name
      national
      Type
      string
    • Name
      international
      Type
      string
  • Name
    country
    Type
    object
    Description
    • Name
      code
      Type
      string
    • Name
      countryCode
      Type
      integer
  • Name
    type
    Type
    object
    Description
    • Name
      title
      Type
      string
    • Name
      description
      Type
      string
  • Name
    isValid
    Type
    boolean
GET/validate/phone/

Validate

This endpoint analyzes a phone number to verify its validity and provide formatted versions according to international standards. It performs checks including:

  • Validity of country code and area code
  • Correct number length for the region
  • Proper number pattern for the specified type
  • Structural compliance with international numbering plans

Mandatory headers

  • Name
    x-api-key
    Type
    string
    Description
    A valid API key obtained through active subscription must be included in the header in order for the endpoint to work.

Required parameters

  • Name
    number
    Type
    string
    Description
    The phone number to validate.
  • Name
    country
    Type
    string
    Description
    The ISO country code (e.g., "AU" for Australia) to use for parsing national numbers.

Request

GET
/validate/phone/
curl "https://api.vigil.sh/validate/phone/?number=0291234567&country=AU" \
-H 'x-api-key: {api-key}'

Response

{
  "result": {
    "numberRaw": "0291234567",
    "numberNormalized": "(02) 9123 4567",
    "formatted": {
      "e164": "+61291234567",
      "national": "(02) 9123 4567",
      "international": "+61 2 9123 4567"
    },
    "country": {
      "code": "AU",
      "countryCode": 61
    },
    "type": {
      "title": "Landline",
      "description": "Fixed-line telephone number"
    },
    "isValid": true
  }
}