Request Contact Info for a Number

❗️
WARNING
This product is deprecated. We recommend using the Telesign Phone ID Contact identity attribute rather than this legacy product.

The legacy Phone ID Contact product delivers contact information related to the subscriber's phone number to provide another set of indicators for established risk engines.

The fastest way to send your first request for contact information is to try out the API Explorer. If you have your Telesign authentication credentials, follow the instructions below to send a request using the API Explorer. You can also use it to get a code snippet in the language of your choice.

Before you begin

Ensure that you have the following:

Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key.

Steps

🚧
CAUTION:
Using your account credentials in the API Explorer to make a request results in your account being charged for the transaction.
You are subject to all compliance rules as appropriate for your transaction.

Open the GET https://rest-ww.telesign.com/v1/phoneid/contact/{complete_phone_number} reference page in a separate window from these instructions.
Go to the AUTHENTICATION header in the upper-right panel of the page. Enter your Customer ID in the Customer ID field and your API Key in the API Key field.
Go to the PATH PARAMS section in the middle panel of the page. In the complete_phone_number field, enter the complete phone number that you want to request information about (include the country code). Do not include any special characters or spaces.
Select Try It! in the right panel to send your request to Telesign. You will be charged the standard rate for this transaction.
You can also select the copy icon to the left of Try It! to copy the code snippet displayed. To change the programming language of the snippet, select one of the options under the LANGUAGE header in the right sidebar.

Congratulations! You've sent your first request and generated a code snippet!

You can see more about available parameters on that same reference page.

General requirements

Authentication: Basic (easiest to implement) and Digest
Endpoint: https://rest-ww.telesign.com/v1/phoneid/contact/[complete_phone_number]
Encoding: Accept only UTF-8 encoded unicode characters as inputs
Accepts: application/x-www-form-urlencoded
Required headers: Content-Type - application/x-www-form-urlencoded

API reference

GET https://rest-ww.telesign.com/v1/phoneid/contact/{complete_phone_number}.

Example

Request

GET https://rest-ww.telesign.com/v1/phoneid/contact/15555551234?ucid=THEF HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: rest-ww.telesign.com

Response

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": "Odessa",
      "state": "TX",
      "zip": "79758",
      "metro_code": "36220",
      "county": "Ector",
      "country": {
         "name": "United States",
         "iso2": "US",
         "iso3": "USA"
      },
      "coordinates": {
         "latitude": 31.8466,
         ""longitude": -102.36778
      },
      "time_zone": {
         "name": null,
         "utc_offset_min": "-6",
         "utc_offset_max": "-6"
      }
   },
   "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"
   }
}