Get Started with Add-ons

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

  • Call Forward Detection - Get information about the call forwarding status of a phone number.
  • 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.)
  • Contact Match - Get a score indicating how closely your name and address for a submitted phone number match the name and address on file with the carrier.
  • 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.

Enable an Add-on

To enable any add-on, speak with our Customer Support Team.

Use an Add-on

Use an add-on by including its associated key as a sub-property of the addons object in the payload:


Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json 

		"addons": {
 			"contact": {}

See the table below for the required key and an example value (including sub-properties) for each add-on:

Add-on Key Example Value
Call Forward Detection call_forward_detection {}
Contact contact {}
Contact Plus contact_plus {"billing_postal_code": "40509"}
Contact Match 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" }
Number Deactivation number_deactivation {"last_verified": "2018-04-05T00:00:00Z"}
Subscriber Status subscriber_status {}
Porting History porting_history {}
Porting Status porting_status {}
SIM Swap sim_swap {}

Most add-ons require only an empty object as the value of the associated property.

Try It

If you have been granted access and credentials for the PhoneID API and have at least one add-on enabled, you can try a test request in the API Explorer below. You can also get a code snippet for the request.

  1. Click the Auth tab and for Username add your Customer ID. For Password add your API key.
  2. In the Settings tab, for the complete_phone_number field, enter the complete phone number that you want to request information about (include the country code).
  3. Click Send.
  4. Click the Code Generation tab and use the Language and Library menus to choose the language you want your code snippet in.
PhoneID API Explorer
When using this API Explorer, you will be charged your contracted rate for each transaction. The time shown is not indicative of regular transmission rates, and only applies to this API Explorer.
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
No $$.env variables are being used in this request.

Try It with cURL

To try the PhoneID API with add-ons using cURL:

  1. Copy one of the commands below into a text editor
  2. Replace $COMPLETE_NUMBER in the command with the phone number you want information for.
  3. Replace $CUSTOMER_ID with your Customer ID from TelePortal
  4. Replace $API_KEY with your API key from TelePortal.
  5. If you are trying out the Call Forward Detection add-on, replace the following parameters with the appropriate values:
    • Replace $METHOD with the way you collected the consent record
    • Replace $TIMESTAMP with the date and time you collected the consent record
  6. Paste the edited command onto the command line and run it.
curl --request POST$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"call_forward_detection":{}},"consent":{"method":"$METHOD","timestamp":"$TIMESTAMP"}}' --user "$CUSTOMER_ID":"$API_KEY"
curl --request POST$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

Check out these related pages: