Formatting and Validation

Lookup's basic request is free to use and provides:

E.164 and national formats
Phone number validation including helpful errors

To make a free formatting and validation request, do not include any Fields in the request.


_10curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}" \ -u 
_10$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Release Stage and Access: Public Beta, available via self-service.

Response properties

Only valid numbers (for a given region, using length, and prefix information) will return results. If you attempt to lookup a phone number which is invalid, you will receive ”valid”: false in the response. In some cases you will also receive a reason for the validation failure in the validation_errors field.

Validation errors property values

The following are the possible values for the Validation Errors property.

TOO_SHORT
TOO_LONG
INVALID_BUT_POSSIBLE
INVALID_COUNTRY_CODE
INVALID_LENGTH
NOT_A_NUMBER

Lookup with valid E.164 phone number

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function fetchPhoneNumber() {
_18  const phoneNumber = await client.lookups.v2
_18    .phoneNumbers("+141599299600")
_18    .fetch();
_18
_18  console.log(phoneNumber.nationalFormat);
_18}
_18
_18fetchPhoneNumber();

Output


_19{
_19  "calling_country_code": "1",
_19  "country_code": "US",
_19  "phone_number": "+141599299600",
_19  "national_format": "(415) 992-9960",
_19  "valid": true,
_19  "validation_errors": null,
_19  "caller_name": null,
_19  "sim_swap": null,
_19  "call_forwarding": null,
_19  "line_status": null,
_19  "line_type_intelligence": null,
_19  "identity_match": null,
_19  "reassigned_number": null,
_19  "sms_pumping_risk": null,
_19  "phone_number_quality_score": null,
_19  "pre_fill": null,
_19  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"
_19}

Lookup with invalid E.164 phone number

Too long