Get Started with Add-ons

Add-ons are features of the PhoneID API that allow you to get additional information about a phone number along with the base details.

The self-service API only supports the Contact add-on. This add-on allows you to retrieve the name, address, and other contact info associated with the subscriber for the phone number you submit. This page walks you through how to use the Contact add-on in a request and provides other details helpful to using it.

Contents of This Page

How to Use It

Follow these steps to use the Contact add-on.

Step 1: Enable the Contact Add-on

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

Step 2: Send a Request with Add-on Parameters

  1. Prepare a request to the PhoneID API, including all the normal requirements (see Get Started).
  2. Also include the addons request body parameter in the payload.
  3. Also include the sub-property contact, with an empty object as its value.
  4. Send your request.


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": {}

Requests to the PhoneID API that include add-ons must use only the application/json content-type. Basic requests without add-ons have more flexibility on content-type.

Try It

If you have credentials for TeleSign APIs and have enabled this add-on, 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 the standard 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

You can also try a test request using cURL:

  1. Copy the command 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. Paste the edited command onto the command line and run it.
curl --request POST$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"contact":{}}}' --user "$CUSTOMER_ID":"$API_KEY"

Additional Request Parameters

See addons and in the Request Body section of the API reference page.

Additional Response Properties

See contact and all of its sub-properties under Schema in the Responses section of the API reference page.



Indicates which add-ons you want to use with this request, and contains any other inputs for use with those add-ons.


Contains properties with data returned by the Contact add-on. Not all of these data points will always be available or applicable.

Status Codes

Status Code Description
2800 Request successfully completed
2801 Invalid add-ons parameter.
2802 This add-on temporarily unavailable.
2803 Phone number out of coverage for this add-on.
2804 Phone number not applicable for this add-on.
2805 No information for this phone number for this add-on.
2806 This 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.
2810 Request processing failed during data collection.