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

Request Contact Info for a Number

The PhoneID Contact API 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 PhoneID Contact API Explorer. If you have your credentials, follow the instructions to use TeleSign’s PhoneID Contact API for the first time. You will also be able to get a code snippet in the language of your choice.

PhoneID Contact API Explorer
NOTE: When using the PhoneID API Explorer, you will be charged your contracted rate for each transaction. The time shown in ms is not indicative of regular transmission rates, adnd only applies to the PhoneID Contact Explorer.
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
No $$.env variables are being used in this request.

Use these instructions with the PhoneID Contact Explorer (above) to send a request for contact information about a specific phone number and get a code snippet for making the request in the language of your choice.

  1. Click the Auth [basic] tab and for **Username add your Customer ID. For Password add your API key.
  2. Click the Settings tab and in the complete_phone_number field, enter your phone number with the country code. Do not include special characters or spaces.
  3. Click Send.
  4. Click the Code Generation tab and use the Language and Library drop-downs to choose the language you want your code snippet in.

Congratulations! You’ve sent your first request for contact information using TeleSign’s PhoneID Contact API and generated a code snippet!

You can see more about available parameters on the GET /v1/phoneid/contact.

The rest of this page details information about the PhoneID Contact API. You can choose from these options:

PhoneID Contact Information

All requests submitted to the PhoneID Contact API:

  • Can be authenticated with Basic (easiest to implement) and Digest
  • Use[complete_phone_number]?ucid=[use_case_code] as the base endpoint
  • Accept only UTF-8 encoded unicode characters as inputs
  • Use Content-Type application/x-www-form-urlencoded in request headers

If you want to see the API reference page, go to GET /v1/phoneid/contact.


This section provides examples of the API. 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"

Next Steps

Here are some suggestions for next steps to take:

  • Contact Add-on - Read about the new Contact add-on that makes it easy to get contact information about a subscriber. It is like the PhoneID Contact API, but better.
  • Contact Plus Add-on - Read about the Contact Plus add-on that gives you a higher quality tier of contact information about a subscriber. It is like the PhoneID Contact API, but better.