PhoneID API - Get Started
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).
Reference Pages
Full technical details for the API, including explanations of each request parameter and response property.
General Requirements
Request Requirements
- Authentication: Basic (easiest to implement) or Digest
- Endpoint:
https://rest-ww.telesign.com/v1/phoneid/{complete_phone_number}
orhttps://rest-ww.telesign.com/v1/phoneid
- Encoding: Accepts only UTF-8 unicode characters as inputs
- MIME Type:
application/json
- Required Headers:
Content-Type
Response Details
- MIME Type:
application/json
NOTE:
As long as you are not including the
addons
object in your request payload, you can also use theapplication/x-www-form-urlencoded
MIME type in your request instead ofapplication/json
.
Actions
Request Details About a Phone Number in Path
Reference Page: POST /v1/phoneid/{complete_phone_number}
Request information about a phone number including phone type, telecom carrier, and location information; the phone number is specified in the path.
Request Details About a Phone Number
Reference Page: POST /v1/phoneid
Request information about a phone number including phone type, telecom carrier, and location information; the phone number is specified in the request body.
Try It
If you have been granted access and credentials for the PhoneID API, you can try a test request in the API Explorer. You can also get a code snippet for the request.
- Click the Auth tab and for Username add your Customer ID. For Password add your API key.
- 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).
- Click Send.
- Click the Code Generation tab and use the Language and Library menus to choose the language you want your code snippet in.
Full technical details for this action, including all available parameters for requests, can be found at POST /v1/phoneid/{complete_phone_number}.
Example
Request
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Date: Tue, 31 Jan 2017 14:51:26 GMT
Content-Type: application/json
{
"account_lifecycle_event": "create",
"originating_ip": "203.0.113.45"
}
Response (body only)
{
"reference_id": "F0123456789ABCDEF0123456789ABCDE",
"status": {
"updated_on": "2015-10-03T14:51:28.709526Z",
"code": 300,
"description": "Transaction successfully completed"
},
"location": {
"city": "Los Angeles",
"state": "CA",
"zip": "90066",
"metro_code": "4480",
"county": "Los Angeles County",
"country": {
"name": "United States",
"iso2": "US",
"iso3": "USA"
},
"coordinates": {
"latitude": 33.99791,
"longitude": -118.42302
},
"time_zone": {
"name": "America/Los_Angeles",
"utc_offset_min": "-8",
"utc_offset_max": "-8"
}
},
"numbering": {
"original": {
"complete_phone_number": "15555551234",
"country_code": "1",
"phone_number": "5555551234"
},
"cleansing": {
"call": {
"country_code": "1",
"phone_number": "5555551234",
"cleansed_code": 100,
"min_length": 10,
"max_length": 10
},
"sms": {
"country_code": "1",
"phone_number": "5555551234",
"cleansed_code": 100,
"min_length": 10,
"max_length": 10
}
}
},
"phone_type": {
"code": "1",
"description": "FIXED_LINE"
},
"blocklisting": {
"block_code": 0,
"block_description": "Not blocked",
"blocked": False
},
"carrier": {
"name": "Verizon"
}
}
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. You can mix and match them to get detailed information about phone numbers, such as device details, porting history, subscriber contact information, and more. For complete details on what add-ons are available, see Get Started with Add-ons.
Response Value Tables
These tables explain the meaning of certain codes and other enumerated values that may be included in the response.
- Country Codes and Dialing Codes
- Phone Number Cleansing Codes - These codes indicate how the phone number in the request was cleansed before use.
- Phone Type Codes
- Time Zones
Updated about 2 months ago