NOTE:

TeleSign recommends using the Contact or Contact Plus add-on rather than this legacy API.

Get Started with the PhoneID Contact API

The PhoneID Contact API delivers contact information related to the subscriber’s phone number to provide another set of indicators for established risk engines.

You can use it to find a subscriber’s:

First Name
Last Name
Street Address
City
State (or Province)
Country
ZIP Code

NOTE:

The information returned by PhoneID Contact includes the information returned by PhoneID.

The PhoneID Contact web service is discussed in the following sections:

Coverage
URI
Supported
Request and Response Parameters
PhoneID Contact API Examples
Next Steps

General Information

All requests submitted to the PhoneID Contact API:

Can be authenticated with Basic (easiest to implement) and Digest
Use https://rest-ww.telesign.com/v1/phoneid/contact/{complete_phone_number} as the base endpoint
Accept only UTF-8 encoded unicode characters as inputs
Use Content-Type application/x-www-form-urlencoded in request headers

Request Contact Info for a Number

For quick instructions about how to request contact information for a phone number, see the Request Contact Info for a Number page.

For a list of available parameters, see the GET /phoneid/contact page.

PhoneID Contact API Examples

This section provides examples of a request and response using the PhoneID Contact API.

Request

You send a GET request message like this one, to the /v1/phoneid/contact/ resource, with your user’s complete phone number as the subresource identifier, and the use-case code as a query parameter.

Example GET Request Message

GET https://rest-ww.telesign.com/v1/phoneid/contact/15555551234?ucid=THEF HTTP/1.1
Accept-Encoding: gzip,deflate
X-TS-Auth-Method: HMAC-SHA256
X-TS-Nonce: 4b33a3af-fd87-421d-b494-dafdc36b0b00
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Date: Wed, 03 Oct 2015 14:51:26 -0700
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
Host: rest-ww.telesign.com

Response

TeleSign returns the following message in response to the preceding example request.

Example Response to a GET Request

HTTP/1.1 200 OK
Date: Wed, 03 Oct 2015 14:51:28 GMT
Server: CERN/3.0 libwww/2.17
Content-Length: 1242
Allow: GET,HEAD
Content-Type: application/json

{
   "reference_id": "0123456789ABCDEF0123456789ABCDEF",
   "sub_resource": "contact",
   "status": {
      "updated_on": "2015-10-03T14:51:28.709526Z",
      "code": 300,
      "description": "Transaction successfully completed"
   },
   "errors": [],
   "location": {
      "city": "PLAYA DEL REY",
      "state": "CA",
      "zip": "90291",
      "metro_code": "",
      "county": "Los Angeles County",
      "country": {
         "name": "United States",
         "iso2": "US",
         "iso3": "USA"
      },
      "coordinates": {
         "latitude": 33.98005,
         "longitude": -118.43566
      },
      "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"
   },
   "carrier": {
      "name": "Verizon"
   },
   "contact": {
      "firstname": "NICHOLS RESTAURANT INC",
      "lastname": "",
      "address1": "4325 GLENCOE AVE",
      "address2": "",
      "address3": "",
      "address4": "",
      "city": "MARINA DEL REY",
      "state_province": "CA",
      "country": "US",
      "zip_postal_code": "902926444"
   }
}

Next Steps

This section provides suggestions for next steps to take.

Request Contact Info for a Number - Learn how to make your first request to the PhoneID Contact API.
GET /phoneid/live - Check out the API reference page for PhoneID Contact.