Want to provide feedback?

Write to docs@telesign.com.

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:

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.