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.

Formatting and Validation Lookup

1curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/%2B14159929960" \
2-u $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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchPhoneNumber() {
11  const phoneNumber = await client.lookups.v2
12    .phoneNumbers("+14159929960")
13    .fetch();
14
15  console.log(phoneNumber.nationalFormat);
16}
17
18fetchPhoneNumber();

Response

1{
2  "calling_country_code": "1",
3  "country_code": "US",
4  "phone_number": "+14159929960",
5  "national_format": "(415) 992-9960",
6  "valid": true,
7  "validation_errors": null,
8  "caller_name": null,
9  "sim_swap": null,
10  "call_forwarding": null,
11  "line_status": null,
12  "line_type_intelligence": null,
13  "identity_match": null,
14  "reassigned_number": null,
15  "sms_pumping_risk": null,
16  "phone_number_quality_score": null,
17  "pre_fill": null,
18  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"
19}

Lookup with invalid E.164 phone number

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchPhoneNumber() {
11  const phoneNumber = await client.lookups.v2
12    .phoneNumbers("+141599299600")
13    .fetch();
14
15  console.log(phoneNumber.valid);
16}
17
18fetchPhoneNumber();

Response

1{
2  "calling_country_code": null,
3  "country_code": null,
4  "phone_number": "+141599299600",
5  "national_format": null,
6  "valid": false,
7  "validation_errors": [
8    "TOO_LONG"
9  ],
10  "caller_name": null,
11  "sim_swap": null,
12  "call_forwarding": null,
13  "line_status": null,
14  "line_type_intelligence": null,
15  "identity_match": null,
16  "reassigned_number": null,
17  "sms_pumping_risk": null,
18  "phone_number_quality_score": null,
19  "pre_fill": null,
20  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+141599299600"
21}