Objective

This article walks you through both Lookup v1 and v2, explaining how each version checks number validity. This is a guide to identifying valid and invalid phone numbers using Twilio's Lookup API.

Product 

Lookup API

Procedure

There are some differences in the process to check number validity between Lookup v1 and v2. We cover both in detail below, but highly recommend using Lookup v2 for the best experience. 

Lookup v1

Lookup v1 will return an HTTP 404 status code if a phone number resource is invalid. Phone number validity is based on international phone numbering plan data administered by the ITU. Though the ITU should in theory have all global numbering plans on file, in practice, not every country will file their numbering plans with the ITU. Additionally, some government authorities may let telecom companies be responsible for administrating numbering plans. As a result of this lack of centralization, maintaining an accurate global numbering plan is a patchwork process. Twilio works with a variety of carrier partners to maintain accurate global numbering plan data but discrepancies can arise as numbering plans change and downstream providers must propagate these changes.
 

Lookup v2

In Lookup v2, the response property 'valid' offers a boolean value signaling if the phone number falls within a valid range freely assignable by carriers. When 'valid' returns as false, the 'validation_errors' property specifies reasons for the number's invalidity, such as TOO_SHORT, TOO_LONG, INVALID_BUT_POSSIBLE, INVALID_COUNTRY_CODE, INVALID_LENGTH, NOT_A_NUMBER.

Moving to Lookup v2 for number validation yields a more comprehensive response, empowering your decisions based on phone number accuracy. If you're still on Lookup v1, we highly recommend migrating to benefit from this robust API. For a seamless transition, follow our guide: Migrate from Lookup V1 to Lookup V2.