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
- Use the addons Parameter
- Try the Contact add-on with cURL
- Request and Response Parameters
- Status Codes
- Next Steps
Configure the Contact Add-on
To configure the the contact add-on parameter, log in to your account at portal.telesign.com and do the following:
- 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.
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 portal.telesign.com 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:
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
body:
{
“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:
- Windows: https://help.zendesk.com/hc/en-us/articles/229136847-Installing-and-using-cURL
- Mac: http://macappstore.org/curl/
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-api.telesign.com/v1/phoneid/<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. |