get

/phoneid/live/{complete_phone_number}

Enter a phone number to receive detailed contact information related to the subscriber’s phone number to provide another set of indicators for established risk engines. NOTE: If you try this API out using the API Explorer, you will be billed for the transaction as you normally would.

Authorization

basic

Request Parameters

1 Path Parameter
1 Query Parameter

Responses

Your request was fulfilled and resulted in a new resource being created. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.

Status Code Associated Text String Description
300 Transaction successfully completed The system was able to obtain all of the requested data for PhoneID.
301 Transaction partially completed The system was able to obtain some of the data for PhoneID, but not all of it.
Error Description
-60001 PhoneID Contact data not found
Schema
object
reference_id
string

A 32-digit hex value used to identify the web service requests. The value is unique to each web service request, is randomly generated by TeleSign, and is returned in the response message immediately following the web service request.

sub_resource
string

A string displaying the subresource accessed. It is set to contact.

errors
object

A JSON object that contains information on error conditions that might have resulted from the request, in an array of propery value pairs. If multiple errors occur, a pair is returned for each error.

Value Description
code A 1 to 5-digit error code (possibly negative) that indicates the type of error that occurred.
description A string that describes the type of error that occurred. If no errors occur, then this array is empty.
phone_type
object

An object containing details about the phone type.

code
string

One of the phone type codes.

description
string

Text describing the phone type.

status
object

An object containing details about the request status.

code
string

One of the status codes or error codes.

description
string

Text describing the transaction status.

updated_on
string

An RFC 3339 timestamp indicating when the transaction status was updated.

numbering
object

An object containing details about the numbering attributes of the specified phone number.

original
object

An object containing details about the original phone number passed to TeleSign’s PhoneID API.

cleansing
object

An object containing details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers.

location
object

An object containing geographical location information associated with the phone number.

city
string

A string specifying the name of the city associated with the phone number.

county
string

A string specifying the name of the County (or Parish) associated with the phone number (U.S. only).

state
string

The 2-letter state abbreviation code of the state (province, district, or territory) associated with the phone number (North America only).

zip
string

The 5-digit United States Postal Service Zip Code associated with the phone number (U.S. only).

country
object

An object containing details about the country associated with the phone number.

time_zone
object

An object containing details about the time zone associated with the phone number. For maximum and minimum UTC offsets, they are specified in units of hours, and range from -12 to +14. For positive numbers, the plus sign (+) may not be returned. Additional offsets due to Daylight Savings Time or Summer Time are not considered. For example, Russia, which spans 11 time zones, has a minimum UTC offset of +2, and a maximum of +12.

coordinates
object

An object containing details about the geographical coordinates of the location where the phone number is registered.

metro_code
string

A 4-digit string indicating the Primary Metropolitan Statistical Area (PMSA) code for the location associated with the phone number (U.S. only). PMSA Codes are governed by the []US Census Bureau](http://www.census.gov/). This information is useful for large metropolitan areas that comprise several smaller cities. For example, the PMSA for Long Beach, California is Los Angeles County, which gives Long Beach the PMSA Code 4480.

carrier
object

An object containing information about the company that provides telecommunications services for the phone number.

name
string

A string specifying the name of the carrier. For example - “Verizon."

live
object

A JSON object containing details about a subscriber and subscriber’s device.

subscriber_status
string

A string indicating the current status of the subscriber’s phone number.

Value Description
ACTIVE The phone number is in service.
DISCONNECTED The phone number is not in service.
device_status
string

A string indicating the current status of the phone equipment.

Value Description
REACHABLE The device is on-line, and is ready to initiate/receive calls. Note that subscriber_status=ACTIVE.
UNAVAILABLE The device status is not available for this phone number.
UNREACHABLE The device is either turned off, or it is out of the coverage area.
roaming
string

A string indicating whether the mobile device is currently roaming outside of the contracted service coverage area.

Value Description
NO The mobile device is not currently roaming.
UNAVAILABLE The service is unable to make a determination at this time.
YES The mobile device is currently roaming.
roaming_country
string

The country in which the mobile device is roaming.

Value Description
A string naming the country The name of the country (in mixed-case).
null The service is unable to make a determination at this time.

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
complete_phone_number
$$.env
2 variables not set
username
password