Want to provide feedback?

Write to docs@telesign.com.

Get Started with Add-ons

PhoneID add-ons allow you to find out many kinds of information associated with a phone number. Choices include:

  • Contact - Get basic contact information about any phone number. (Consent not required.)
  • Contact Plus - Get high quality contact information about any phone number by tapping into additional data sources. (Consent required.)
  • Device Info - Get the phone manufacturer and model.
  • Number Deactivation - Find out if and when a phone number was deactivated, and by which carrier.
  • Subscriber Status - Find out whether the phone is prepaid, post paid, who the primary account holder is, and how long the particular status has been maintained.
  • Porting History - Find out when a phone number was ported, where it was ported to, and by who.
  • Porting Status - Find out the current MCC (mobile country code) and the current MNC (mobile network code).
  • Sim Swap - Find out whether or not the SIM card for the phone has been swapped or not, and when.

Configure an Add-on

To enable any add-on, speak with your Customer Success Manager (CSM).

Use an Add-on

You use an add-on in the body of your request like so:

POST Request for the Contact Add-on with application/json
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json 

		“addons”: {
 			“contact”: {}
Add-on API Request Term
Contact "contact":{}
Contact Plus "contact_plus":{zip_code}"
Contact Match Any of "contact_match":{ "first_name": "Peter", "last_name": "Petersen", "address": "1444 S. Alameda Street Los Angeles", "city": "San Jose", "postal_code": "95120", "state": "CA", "country": "USA" }
Device Info "device_info":{}
Number Deactivation "number_deactivation":{}
Subscriber Status "subscriber_status":{}
Porting History "porting_history":{}
Porting Status "porting_status":{}
Sim Swap "sim_swap":{}

Try an Add-on with cURL

cURL is a software project that provides a library and command-line tool for transferring data using various protocols. You can use it to quickly do API calls if the API you query allows basic authentication. cURL is available for Mac and Windows. If you have never used it, you can learn about how to install it from these sources:

After you have it installed, you would send this cURL command with your add-on included (you must replace complete-number in the --request line, the CUSTOMER_ID, and API_KEY values with your customer ID and API key, or it will not work):

curl --request POST https://rest-ww.telesign.com/v1/phoneid/<complete-number> --header "Content-Type: application/json" --data '{"addons":{"contact":{}}}' --user "CUSTOMER_ID":"API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/<complete-number> --header "Content-Type: application/json" --data '{"addons":{"porting_history":{}}}' --user "CUSTOMER_ID":"API_KEY"

Status Codes

Status Code Description
2800 Request successfully completed
2801 Invalid request addons parameter: {parameter_name}.
2802 name of add-on add-on temporarily unavailable.
2803 Phone number out of name of add-on add-on coverage.
2804 Phone number not applicable in name of add-on add-on.
2805 No name of add-on add-on information for phone number.
2806 Name of add-on add-on is not enabled.
2807 Some parameters submitted in the request are not valid.
2808 Invalid Request: {parameter_name} parameter is missing or empty.
2809 Billing Postal Code does not match contact_plus add-on information for phone number.
2810 Request process failed during data collection.
2811 Request processing timeout.
2812 name of add-on exceeded transaction hard cap. Request denied.

Next Steps

This section offers some suggestions for next steps to take.