Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

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.


_10
curl -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

response-properties page anchor

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

type-property-values page anchor

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

lookup-with-valid-e164-phone-number page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v2.phoneNumbers('+141599299600')
_10
.fetch()
_10
.then(phone_number => console.log(phone_number.nationalFormat));

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

lookup-with-invalid-e164-phone-number page anchor

Too long

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v2.phoneNumbers('+141599299600')
_10
.fetch()
_10
.then(phone_number => console.log(phone_number.valid));

Output

_21
{
_21
"calling_country_code": null,
_21
"country_code": null,
_21
"phone_number": "+141599299600",
_21
"national_format": null,
_21
"valid": false,
_21
"validation_errors": [
_21
"TOO_LONG"
_21
],
_21
"caller_name": null,
_21
"sim_swap": null,
_21
"call_forwarding": null,
_21
"line_status": null,
_21
"line_type_intelligence": null,
_21
"identity_match": null,
_21
"reassigned_number": null,
_21
"sms_pumping_risk": null,
_21
"phone_number_quality_score": null,
_21
"pre_fill": null,
_21
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+141599299600"
_21
}


Rate this page: