Skip to main content

Removing Landlines From Your Recipient List and Gathering Additional Information

Sending to landlines isn't a good idea due to messaging support differing greatly between providers. Additionally, even if the support is there but you wish to have recipients interact with your content, through a link to your website, for example, the user experience really starts to break down. With this code example you will be able to start sending to wireless numbers only.

Full code example: Remove landlines from messaging list using Phone Number Lookups
import base64
import requests
import pandas as pd

# ENTER AUTHENTICATION
space = 'YOUR_SPACE.signalwire.com'
Project_ID = '5671abb4-bad3-4fb3-8f80-XXXXXXXXXXXXX'
API_Token = 'PT3c865e1c33f803f7d47fa178d5XXXXXXXXXXXXXXXX'

# ENTER NUMBERS TO SCRUB
# We will list out all numbers in our 'customer' list, the list below is a list of random numbers that you may test this code with
numbers_to_check=['+16023580034', '+19138032451', '+19138032455', '+14803769009', '+17167718294', '+11111111111', '+14802005061', '+14802015033', '+18082817937', '+18082008666']

# Create an array for each column in our final dataframe of wireless recipients
line_type_list =[]
line_location_list =[]
line_city_list =[]
sms_enabled_number_list=[]
line_carrier_list =[]

# For our Relay-Rest APIs we will use a base64 encoded string of your projectID and API Token
base_64_token = Project_ID + ':' + API_Token
message_bytes = base_64_token.encode('ascii')
base64_bytes = base64.b64encode(message_bytes)
base_64_token = base64_bytes.decode('ascii')

# The Number Lookup APIs are Relay-Rest so we must make an http request to the end points
# and declare what content to accept. We must also declare the content type and our Authorization Token which is base64 encoded
headers = {
"Accept": "application/json",
"Content-Type": "application/x-www-form-urlencoded",
"Authorization": "Basic "+ base_64_token}


for i in numbers_to_check:
# Declare the url for our Number Dip API this will iterate through each number we are requesting to lookup
number_lookup_url= "https://" + space + '/api/relay/rest/lookup/phone_number/' + i + '?include=carrier'
# Make the complete API request for our Number Dip API
number_lookup_API_Request = requests.request("GET", number_lookup_url, headers=headers)
# Read the response from the API by accessing the json that was returned
number_assignment_json = number_lookup_API_Request.json()

# Find the type of number, whether landline or wireless
line_type = number_assignment_json['carrier']['linetype']

# If the number is sms enabled, we will append our dataframe with it's e164 format, the location and the type of number
if line_type == 'wireless':
# Let the console know which numbers will be added to our dataframe
print(i + ' is a wireless number')
line_type_list.append(line_type)

# Create a list of all numbers that are wireless enabled. This list will become a column in our final dataframe
sms_enabled_number= number_assignment_json['e164']
sms_enabled_number_list.append(sms_enabled_number)

# Create a list of the state of each number that is wireless enabled. This list will become a column in our final dataframe
line_location = number_assignment_json['location']
line_location_list.append(line_location)

# Create a list of the cities of each number that is wireless enabled. This list will become a column in our final dataframe
line_city = number_assignment_json['carrier']['city']
line_city_list.append(line_city)

# Create a list of the carriers of each number that is wireless enabled. This list will become a column in our final dataframe
line_carrier = number_assignment_json['carrier']['lec']
line_carrier_list.append(line_carrier)
else:
# Let the console know which numbers will NOT be added to our dataframe
print(i + ' is NOT a wireless number')

# Turn each of our columns into a complete data frame
final_dataframe= pd.DataFrame(({'SMS_Numbers': sms_enabled_number_list, 'Number Type': line_type_list, 'Carrier': line_carrier_list, 'State': line_location_list, 'City': line_city_list}))

# Display all rows and columns of the final_dataframe
pd.set_option('display.max_rows', None)
pd.set_option('display.width', None)
pd.set_option('display.max_columns',None)
# Lets print out our dataframe and see what this all looks like!
print()
print(final_dataframe,"\n")
print( 'Your messaging list has been scrubbed, looks like these are the numbers you should send to:')
print(sms_enabled_number_list)

# UNCOMMENT TO EXPORT SMS_ENABLED_NUMBER_LIST TO CSV
final_dataframe.SMS_Numbers.to_csv('sms_enabled_number_list.csv', index=False, encoding='utf-8')

What are we going to do?

This snippet incorporates SignalWire's Phone Number Lookup APIs to determine which numbers in your recipient list are wireless and which are landlines. When making this API request, there are many other useful parameters to look at. This is why the code snippet will export a data table with more information about the numbers that are SMS enabled in your customer list.

In order to create a data table, this application will make an API request for each number that is being investigated. By digging through the JSON returned, the number can then be found to be either wireless or landline. Once the number is found to be wireless, the code will also retrieve the carrier, state, and city.

Lastly, we will demonstrate how to format all of these pieces from the JSON responses into a final data frame of recipient information as well as how to export our list of E.164 formatted wireless numbers that are ready to receive messages.

Python

What do you need to run this code?

This code will require a python environment, as well as the assistance the following libraries (you can click on their names to get installation instructions):

What do you need to replace in this code?

ProjectID - Your project ID is an alphanumeric string that tells the SignalWire SDK where to find your project. You can find this in an easily copyable format by going to your
SignalWire Portal and clicking the API tab on the left-hand side.

API_Token - Your Auth Token is an alphanumeric string that helps to authenticate your HTTP requests to SignalWire. You can create this (if you haven’t already) or copy this in an easily copyable format by going to your SignalWire Portal and clicking the API tab. If you have not created an API token, press the blue new button. If you have, click show and copy the string.

space - Your Space URL is the domain of your Space, i.e. example.signalwire.com. This can also be found in an easily copyable format within the API tab in your SignalWire Space.

numbers_to_check - The list of numbers that you would like to search through. You can upload it as a csv or manually enter each one of these numbers. Just make sure that they are in proper E164 format, similar to the example list.

Code Walkthrough

Load necessary libraries

import base64
import requests
import pandas as pd

Prepare SignalWire credentials and numbers list

# ENTER AUTHENTICATION
space = 'YOUR_SPACE.signalwire.com'
Project_ID = '5671abb4-bad3-4fb3-8f80-XXXXXXXXXXXXX'
API_Token = 'PT3c865e1c33f803f7d47fa178d5XXXXXXXXXXXXXXXX'

# ENTER NUMBERS TO SCRUB
# We will list out all numbers in our 'customer' list, the list below is a list of random numbers that you may test this code with
numbers_to_check=['+16023580034', '+19138032451', '+19138032455', '+14803769009', '+17167718294', '+11111111111', '+14802005061', '+14802015033', '+18082817937', '+18082008666']

Prepare data structures

Here we create an array for each column in our final dataframe of wireless recipients.

line_type_list =[]
line_location_list =[]
line_city_list =[]
sms_enabled_number_list=[]
line_carrier_list =[]

Prepare authentication to use when connecting to the API endpoint

# For our Relay-Rest APIs we will use a base64 encoded string of your projectID and API Token
base_64_token = Project_ID + ':' + API_Token
message_bytes = base_64_token.encode('ascii')
base64_bytes = base64.b64encode(message_bytes)
base_64_token = base64_bytes.decode('ascii')

# The Number Lookup APIs are Relay-Rest so we must make an http request to the end points
# and declare what content to accept. We must also declare the content type and our Authorization Token which is base64 encoded
headers = {
"Accept": "application/json",
"Content-Type": "application/x-www-form-urlencoded",
"Authorization": "Basic "+ base_64_token}

Iterate through the list of numbers

Here we do a lookup for each number in numbers_to_check and if it is a wireless number we get more information, but if it is a landline we just print to the console confirming it is not a wireless number.

for i in numbers_to_check:
# Declare the url for our Number Dip API this will iterate through each number we are requesting to lookup
number_lookup_url= "https://" + space + '/api/relay/rest/lookup/phone_number/' + i + '?include=carrier'
# Make the complete API request for our Number Dip API
number_lookup_API_Request = requests.request("GET", number_lookup_url, headers=headers)
# Read the response from the API by accessing the json that was returned
number_assignment_json = number_lookup_API_Request.json()

# Find the type of number, whether landline or wireless
line_type = number_assignment_json['carrier']['linetype']

# If the number is sms enabled, we will append our dataframe with it's e164 format, the location and the type of number
if line_type == 'wireless':
# Let the console know which numbers will be added to our dataframe
print(i + ' is a wireless number')
line_type_list.append(line_type)

# Create a list of all numbers that are wireless enabled. This list will become a column in our final dataframe
sms_enabled_number= number_assignment_json['e164']
sms_enabled_number_list.append(sms_enabled_number)

# Create a list of the state of each number that is wireless enabled. This list will become a column in our final dataframe
line_location = number_assignment_json['location']
line_location_list.append(line_location)

# Create a list of the cities of each number that is wireless enabled. This list will become a column in our final dataframe
line_city = number_assignment_json['carrier']['city']
line_city_list.append(line_city)

# Create a list of the carriers of each number that is wireless enabled. This list will become a column in our final dataframe
line_carrier = number_assignment_json['carrier']['lec']
line_carrier_list.append(line_carrier)
else:
# Let the console know which numbers will NOT be added to our dataframe
print(i + ' is NOT a wireless number')

Prepare dataframe, print it, and export to CSV

# Turn each of our columns into a complete data frame
final_dataframe= pd.DataFrame(({'SMS_Numbers': sms_enabled_number_list, 'Number Type': line_type_list, 'Carrier': line_carrier_list, 'State': line_location_list, 'City': line_city_list}))

# Display all rows and columns of the final_dataframe
pd.set_option('display.max_rows', None)
pd.set_option('display.width', None)
pd.set_option('display.max_columns',None)
# Lets print out our dataframe and see what this all looks like!
print()
print(final_dataframe,"\n")
print( 'Your messaging list has been scrubbed, looks like these are the numbers you should send to:')
print(sms_enabled_number_list)

# UNCOMMENT TO EXPORT SMS_ENABLED_NUMBER_LIST TO CSV
final_dataframe.SMS_Numbers.to_csv('sms_enabled_number_list.csv', index=False, encoding='utf-8')

The Output

A screenshot of the printed output of the dataframe.  A table organizes numbers by number, type (wireless or landline), Carrier, State, an City. A dialog reads 'Your messaging list has been scrubbed, looks like these are the numbers you should send to'.
A screenshot of the printed output.

Wrap up

This code introduced you to the Phone Number Lookup API , to remove any landlines in your message recipient list. We learned how to make an HTTP request to retrieve a JSON response that will list out information about each number. Through this response, we created a data table using pandas and created a formatted list of numbers that are waiting for you to send to!

Getting Started Guide

If you are looking for more information about using SignalWire, refer to our Getting Started guide.
Please feel free to reach out to us on our Community Slack or create a Support ticket if you need guidance!

Sign Up Here

If you would like to test this example out, create a SignalWire account and Space.

Please feel free to reach out to us on our Community Slack or create a Support ticket if you need guidance!