Add-on Overview

The PhoneID API is a REST API that provides a cleansed phone number, phone type, and telecom carrier information that can be used to determine which phone numbers are a potential fraud risk, and what the best communication method for a phone number is (voice, SMS).

You can get more out of your requests by including the Contact add-on. This add-on allows you to get additional information about a phone number without needing to implement a separate API.

Read more about the Contact add-on in these sections:

Configure the Contact Add-on

To configure the the contact add-on parameter, log in to your account at and do the following:

  1. From the left navigation menu, click PhoneID.
  2. From the list of choices that appear under PhoneID, click Settings.
  3. Under the Add-Ons section, turn the switch for Contact Add-On Enabled to Enabled.

Use the addons Parameter

You should use the addons parameter with a header where the content type is application/json. The parameter must be enabled at under your account (refer to Configure an Add-on). You must include the addons parameter in your request to get the extra information in the response. If you do not include this parameter then what you get back is just normal PhoneID information.

Put the parameter in the body of your request as a JSON object. It would look like this:

Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Content-Type: application/json; charset=utf-8
Date: Tue, 31 Jan 2017 14:51:26 GMT


	“addons”: {
		“contact”: {}

Try the Contact 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<complete-number> --header "Content-Type: application/json" --data '{"addons":{"contact":{}}}'--user "CUSTOMER_ID":"API_KEY"

Request and Response Parameters

This section describes the request parameters for add-ons. You use application/json to send your request, you can include any normal PhoneID parameters, and then whatever is required for the add-on you are interested in using. The add-on must be enabled to work.

Request Parameters


The addons parameter for Standard TeleSign products allows you to receive information returned from Contact depending on whether you have it enabled. You receive add-on information back along with standard PhoneID information.

Response Parameters

Response parameters you get back include:

  • All standard PhoneID information you would get back from a regular request to the PhoneID API.
  • All information for each add-on you included in your request.

This is a container for all information returned by the contact add-on in a response. Not all information may be available or applicable for each parameter returned.

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 processing failed during data collection.