Use PhoneID Add-ons

from requests.auth import HTTPBasicAuth
import requests

url = 'https://rest-ww.telesign.com/v1/phoneid/<complete_phone_number>'
headers = {'Accept' : 'application/json', 'Content-Type' : 'application/json'}
r = requests.post(url, auth=HTTPBasicAuth('CUSTOMER_ID', 'API_KEY'), json={'addons':{'addon1':{}, 'addon2':{}}}, headers=headers)

print(r.content)

This tutorial describes how to implement PhoneID add-ons using basic authentication. An add-on lets you easily request additional information about a phone number using the PhoneID API without doing a lot of extra implementation work. When you include an add-on in your request to the PhoneID API, you get back all of the information normally provided by the PhoneID API, and then whatever information is specific to the add-on.

You get back status information for each part of your request. For example, if you send a request to the PhoneID API, and you include a request for information from the Contact add-on and the Number Deactivation add-on, you would get back PhoneID information and status information about the PhoneID part of your request, Contact information and status information about the Contact add-on part of your request, and Number Deactivation information and status information about the Number Deactivation part of your request.

Available add-ons you may want to implement include:

  • Contact Add-on - allows you to retrieve the name and address associated with the phone number you submit, without requesting explicit consent from your end user.
  • Contact Plus Add-on - requires explicit consent from your end users, and once obtained, allows TeleSign to directly access a subscriber’s name and address on file with the carrier.
  • Contact Match Add-on - allows you to compare a name and address for a submitted phone number in your request with a name and address on file with the carrier and return a score referred to as a match score that tells you how close a match was found.
  • Current Location Add-on - provides you with roaming location or roaming status for a device.
  • Current Location Plus Add-on - provides you with roaming location or roaming status for a device.
  • Device Info Add-on - allows you to provide an end-user phone number and receive its phone manufacturer and model to detect fraud or understand the value or risk of the device holder and adjust content and marketing strategies per device.
  • Number Deactivation Add-on - allows you to find out whether a phone number has been deactivated, when it was deactivated, and by which carrier the phone number was deactivated based on carriers’ phone number data and TeleSign’s proprietary analysis.
  • Subscriber Status Add-on allows you to provide an end-user phone number and receive their current carrier subscriber status (prepaid or postpaid; active, suspended, deactivated; account type; primary account holder; length of account tenure) to understand the strength, value or risk of a user.
  • Porting History Add-on allows you to find out at what point and where a phone number was ported to.

Requirements

  • customer ID - obtain from your account by logging in to teleportal.telesign.com
  • API key - obtain from your account by logging in to teleportal.telesign.com
  • Add-on access - you must choose the add-on you want to use and make sure it is enabled. Otherwise, you will not get a successful response.

Use PhoneID Add-ons

This section walks through the code. The code sample shows you how to send a request for the Contact add-on.

  1. You will need the requests module to send your request and HTTPBasicAuth from requests.auth.
Python
from requests.auth import HTTPBasicAuth
import requests
  1. Insert values for the following items:

    • complete_phone_number - the phone number you want to request information about.
    • CUSTOMER_ID - your customer ID, available in TelePortal.
    • API_KEY - your API key, available in TelePortal.
    • Add-ons - review the documentation for your add-on to see how to present it. Most add-ons take the form of 'addon':{}. You can delete addon2 if you do not want to do two add-ons.
  2. Run the program. You can review the documentation for the add-ons you selected to see what the response should look like.