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.
How to Use It
Follow these steps to use the Contact add-on.
Step 1: Enable the Contact Add-on
- Log in to your account at portal.telesign.com
- From the left navigation menu, click PhoneID.
- From the list of choices that appear under PhoneID, click Settings.
- Under the Add-Ons section, turn the switch for Contact Add-On Enabled to Enabled.


Step 2: Send a Request with Add-on Parameters
- Prepare a request to the PhoneID API, including all the normal requirements (see Get Started).
- Also include the
addons
request body parameter in the payload. - Also include the sub-property
contact
, with an empty object as its value. - Send your request.
Example:
Request
POST https://rest-api.telesign.com/v1/phoneid/15555551212
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": {}
}
}
CAUTION:
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. You can also get a code snippet for the request.
- Open the reference page for the POST /phoneid/{complete_phone_number} endpoint.
- Under the AUTHENTICATION header in the right panel of the page, put your Customer ID in the username field and your API key in the password field.
- Under the PATH PARAMS header in the middle panel of the page, enter the complete phone number (including country code) that you want information about in the complete_phone_number field. Do not include any special characters or spaces.
- Click Try It! in the right panel to see your transaction. You will be charged the standard rate for your transaction, and you are subject to all compliance rules as appropriate for your transaction.
- If you want you can also click the copy icon to the left of Try It! to copy the code snippet displayed. To change the programming language of the snippet, select one of the options under the LANGUAGE header in the right sidebar.
Try It with cURL
You can also try a test request using cURL:
- Copy the command below into a text editor
- Replace
$COMPLETE_NUMBER
in the command with the phone number you want information for. - Replace
$CUSTOMER_ID
with your customer ID from TelePortal - Replace
$API_KEY
with your API key from TelePortal. - Paste the edited command onto the command line and run it.
curl --request POST https://rest-api.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"contact":{}}}' --user "$CUSTOMER_ID":"$API_KEY"
Additional Request Parameters
See addons
and addons.contact
in the Body Params section of the API reference page.
Additional Response Properties
See contact
and all of its sub-properties on the PhoneID API reference page.
Schema
Request
Parameter | Type | Description |
---|---|---|
addons | object | Indicates which add-ons you want to use with this request, and contains any other inputs for use with those add-ons. |
addons.contact | object | Includes the Contact add-on in processing your request. The value should always be an empty object. |
Response
Property | Type | Description | Example |
---|---|---|---|
contact | object | Contains properties with data returned by the Contact add-on. Not all of these data points will always be available or applicable. | |
contact.address1 | string | The name of the street for the address. | |
contact.address2 | string | The unit or suite number for the address. | |
contact.address3 | string | The town, city, or state. | |
contact.city | string | The city component of the address. | |
contact.country | string | The country component of the address. | |
contact.first_name | string | The first name of the person associated with the address. | |
contact.last_name | string | The last name of the person associated with the address. | |
contact.state_province | string | The state or province component of the address. | |
contact.status | object | Contains sub-properties informing you of the success or failure of your request. | |
contact.status.code | integer | A status or error code indicating what happened after your request. | 2800 |
contact.status.description | string | A brief description of what the error or status code means. | Request successfully completed |
contact.zip_postal_code | string | The ZIP code component of the address. | 40509 |
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. |
Updated 8 months ago