PhoneID Contact API Overview

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

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

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


PhoneID Contact is available in the United States and limited parts of Canada.


The PhoneID Contact web service is exposed with a URI of the form:[complete_phone_number]?ucid=[use_case_code]


The PhoneID Contact API supports the following:

  • Authentication - Basic (easiest to implement) and Digest
  • HTTP Methods -
    • GET - You can retrieve the results of the message you sent using the GET method. You do this by sending a GET request containing the reference id for the message you sent. TeleSign returns a response message in the form of a JSON object in the entity body.
  • Content-Type - application/x-www-form-urlencoded

Request and Response Parameters

For a complete list of request and response parameters, refer to:

PhoneID Contact API Examples

This section contains an example of a typical request-response transaction for invoking the PhoneID Contact web service.


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
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


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
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"