210

Validate Mobile Phone Numbers

If you send Twilio SMS or WhatsApp messages, you may want to make sure that you’re not trying to send messages to landlines or phone number types that you can’t deliver SMS and WhatsApp messages to.

You can solve this problem using Twilio’s lookup API, to people’s phone numbers, carriers, and line types (like mobile, landline, or VoIP) and make sure that you only send SMS and WhatsApp messages to valid recipients! This can help you prevent bounces, and filter out undeliverable messages.

As a part of this recipe, you’ll:

1. Create a segment to capture all people with a phone attribute.
2. Send people in this segment through a campaign that calls Twilio’s lookup API.
3. Capture carrier.type from the webhook response as a phone_type attribute value. This attribute will determine whether a phone number belongs to a mobile device, landline, or VoIP system. Below is an example of a response from Twilio’s lookup API.

{
  "caller_name": null,
  "carrier": {
    "error_code": null,
    "mobile_country_code": "310",
    "mobile_network_code": "456",
    "name": "verizon",
    "type": "mobile"
  },
  "country_code": "US",
  "national_format": "(510) 867-5310",
  "phone_number": "+15108675310",
  "add_ons": null,
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310"
}

Prerequisites

Before you can validate people’s phone numbers, you need:

• A Twilio account and an active payment method. At the time this article is published, each phone number you validate costs $0.005 (Twilio’s lookup API costs $0.005 per request).
• People in your workspace with a phone attribute. Your phone attribute must store values in the standard, E.164 format.

Recipe

As a part of this recipe, we’ll capture the carrier type—which tells us whether or not a phone number belongs to a mobile deivce, landline, or VoIP device—but you can capture any of the fields from Twilio’s lookup API as attributes using this process.

1. Set up a data-driven segment of people with a phone attribute—ensuring that the attribute “exists”. This segment represents the people we want to validate with Twilio’s lookup API.

   

   

2. Create a campaign that filters for the segment you created in the previous step with the following settings:

   • What causes a person to ender a campaign?: They meet conditions.
   • Define the trigger condition: You can use any condition, but we’re using the Signed up condition to start our campaign, because we want to identify people’s phone number type as soon as possible.
   • Filter: The segment you created in the previous step. We only want people to enter the campaign if they have a phone attribute.

   

   

3. In the Workflow step, add a Webhook action and click Add Content.

4. Set up the webhook Request:

   1. Set the method to Get.
   2. Set the request URL to:

   https://[YourTwilioAccountId]:[Your TwilioAuthToken]@lookups.twilio.com/v1/PhoneNumbers/{{ customer.phone | encode }}?Type=carrier
   

   You can get your Twillio account ID and auth token from your Twilio account. {{ customer.phone | encode }} represnts a URL-safe version of each person’s phone number.

   

   

5. Go to the Response tab and set an attribute using the {{response.carrier.type}} property. This captures the type of device—mobile, landline, or VoIP.

   

   

6. Click Send a test to try your webhook using the profile in the Sample Data sidebar. Assuming you’ve set everything up correctly, you’ll see a complete webhook response.

7. Start your campaign.

Whenever someone signs up and has a phone attribute, you will automatically obtain the line type. You can then segment based on this type to send SMS-based messages and campaigns.