TeleSign Developer Center

Welcome! This resource hub provides documentation and references on API & SDK integration and other product-related information.

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Standard PhoneID API

The PhoneID API is a REST API that provides a cleansed phone number, phone type, and telecom carrier information that can be used to determine which phone numbers are a potential fraud risk, and what the best communication method for a phone number is (voice, SMS).

READ THIS NOTE:

This documentation is intended for you if you use the Standard versions of TeleSign products. If you are using TeleSign's free trial, you are using Standard TeleSign products.

You use Standard TeleSign products if you log in to your account at portal.telesign.com, use
endpoints that begin with rest-api.telesign.com, and do not have a designated Technical Account Manager (TAM).

If you log in to your account at teleportal.telesign.com, have endpoints that begin with rest.telesign.com or rest-ww.telesign.com, and have a TAM, you need the Enterprise PhoneID API page instead.

Implement the PhoneID API with an SDK

TeleSign recommends using one of the SDKs as the SDKs handle authentication for you and are available in Java, Python, Ruby, Java, C#, and PHP.

The following Quick Starts can help you get started with the PhoneID API:

Additionally, you should review the Request Parameters section and the Response Parameters section, which contains details about the parameters you can include in requests, as well as what parameters are returned in responses.

TeleSign strongly recommends using an SDK to implement the PhoneID API, because authentication is handled for you. If you decide you want to do it without an SDK anyway, this section provides the formatting information and self implementation specific details you need to take into consideration for your implementation.

Authentication

Access to TeleSign web services is restricted. To receive results for any call you make to a TeleSign web service, you must digitally sign your request message with valid credentials. You sign a request by creating a signature and adding it to your message’s Authorization header. The signature is your message authentication code (MAC). When received by TeleSign, the shared secret API key is used to hash details about the message. A successful match results in successful authentication and a response from the TeleSign web service you called.

To get started, you should review the basic steps for setting up authentication. Review the following:

Additionally, for an example of how to implement authentication, you can take a look at how TeleSign does it for the SDKs. Click the link for the appropriate language to see how TeleSign implements authentication.

URI

The PhoneID web service is exposed with a URI of the form:

https://rest-api.telesign.com/v1/phoneid/<complete_phone_number>

Subresource Identifier

complete_phone_number

  • [Required] Your end user’s phone number, as a string of digits without spaces or punctuation, beginning with the country dialing code (for example, “1” for North America).
  • [Example] 15555551212

Supported HTTP Method

POST

Information Returned
PhoneID returns the following pieces of information:

  • Phone Type
  • Phone Numbering
    • Original Number
    • Cleansing Details
  • Phone Location (geographic parameters are based on registration location)
    • City
    • County
    • State
    • ZIP Code
    • Country
    • Time Zone
    • Coordinates
    • Metro Code
  • Carrier
    • Name

The following example URI calls the PhoneID web service to run a query on the phone number +1 (555) 555-1212.

https://rest-api.telesign.com/v1/phoneid/<complete_phone_number>

Request Parameters

POST requests for the PhoneID web service can include the following parameters:

account_lifecycle_event

  • [Optional] The account lifecycle event parameter allows you to send information about what stage an end user was in when you retrieved information about their phone number. Acceptable values for this parameter are:
    • create - For the creation of a new account.
    • sign-in - For when an end user signs in to their account.
    • transact - For when an end user completes a transaction within their account.
    • update - For when an update is performed, such as an update of account information or similar.
    • delete - For when an account is deleted.

originating_ip

  • [Optional] Your end user’s IP Address (do not send your own IP address). This value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Textual Representation of IPv4 and IPv6 Addresses.
  • [Example] originating_ip=203.0.113.45

Response Parameters

The response message transfers an entity-body containing the web service results— in JavaScript Object Notation (JSON).

reference_id

  • A 32-digit hex value used to identify the web service request. The value is unique to each web service request, is randomly-generated by TeleSign, and is returned in the response message immediately following the web service request.

phone_type

  • An object containing details about the phone type. This object contains the following parameters:
    ValueDescription
    codeOne of the phone type codes
    descriptionText describing the phone type

status

  • An object containing details about the request status.
    ValueDescription
    codeOne of the status codes or error codes.
    descriptionText describing the transaction status
    updated_onAn RFC 3339 timestamp indicating when the transaction status was updated

numbering

  • An object containing details about the numbering attributes of the specified phone number. This object contains the following parameters:
  • original
  • An object containing details about the original phone number passed to TeleSign's PhoneID API. It comprises the following data:
    ValueDescription
    phone_numberThe base phone number. This is simply the phone number without the country dialing code.
    complete_phone_numberThe base phone number prefixed with the country dialing code.
    country_codeA 1, 2, or 3-digit number representing the country dialing code. For example, the country dialing code for both the U.S.A. and Canada is 1, and the country dialing code for the United Kingdom is 44.
  • cleansing
  • An object containing details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers. This object contains the following parameters:
      call
    • An object containing cleansing details about a phone number used for receiving voice calls. This object contains the following parameters:
      ValueDescription
      cleansed_codeOne of the phone number cleansing codes describing the cleansing operation TeleSign performed on the phone number. The default value is 100 (No changes were made to the phone number).
      country_codeA 1, 2, or 3-digit number representing the country dialing code. For example, the country dialing code for both the U.S.A. and Canada is 1, and the country dialing code for the United Kingdom is 44.
      max_length The maximum number of digits allowed for phone numbers with this particular country dialing code.
      min_lengthThe minimum number of digits allowed for phone numbers with this particular country dialing code.
      phone_numberThe base phone number. This is simply the phone number without the country dialing code.
    • sms
    • An object containing cleansing details about a phone number used for receiving text messages. This object contains the following parameters:
      ValueDescription
      cleansed_codeOne of the phone number cleansing codes describing the cleansing operation TeleSign performed on the phone number. The default value is 100 (No changes were made to the phone number).
      country_code A 1, 2, or 3-digit number representing the country dialing code. For example, the country dialing code for both the U.S.A. and Canada is 1, and the country dialing code for the United Kingdom is 44.
      max_lengthThe maximum number of digits allowed for phone numbers with this particular country dialing code.
      min_lengthThe minimum number of digits allowed for phone numbers with this particular country dialing code.
      phone_numberThe base phone number. This is simply the phone number without the country dialing code.

location

  • An object containing geographical location information associated with the phone number. This object contains the following parameters:
  • city
  • A string specifying the name of the city associated with the phone number.
  • county
  • A string specifying the name of the County (or Parish) associated with the phone number (U.S. only).
  • state
  • The 2-letter state abbreviation code of the state (province, district, or territory) associated with the phone number (North America only).
  • zip
  • The 5-digit United States Postal Service ZIP Code associated with the phone number (U.S. only).
  • country
  • An object containing details about the country associated with the phone number. This object contains the following parameters:
    ValueDescription
    iso2The ISO 3166-1 2-letter country code associated with the phone number.
    iso3The ISO 3166-1 3-letter country code associated with the phone number.
    nameThe country name associated with phone number.
  • time_zone
  • An object containing details about the time zone associated with the phone number. This object contains the following parameters:
    ValueDescription
    nameA string identifying the Time Zone Name (TZ) associated with the phone number (U.S. only). For example: “America/Los_Angeles”.
    utc_offset_maxFor international phone numbers, this parameter returns the maximum UTC offset for the country associated with the phone number. For U.S. domestic phone numbers, this parameter returns the same result as utc_offset_min.
    utc_offset_minFor U.S. domestic phone numbers, this parameter returns the UTC offset associated with the phone number. For international phone numbers, this parameter returns the minimum UTC offset for the country associated with the phone number.
    Minimum and maximum UTC offsets are specified in units of hours, and range from -12 to +14. For positive numbers, the plus sign (+) may not be returned. Additional offsets due to Daylight Savings Time or Summer Time are not considered. For example, Russia, which spans 11 time zones, has a minimum UTC offset of +2, and a maximum of +12.
  • coordinates
  • An object containing details about the geographical coordinates of the location where the phone number is registered.
    • Latitude specifies the North-South position of a point on the Earth’s surface. It is an angular measurement that ranges from 0° at the Equator, to 90° at the North Pole (and -90° at the South Pole).
    • Longitude specifies the East-West position of a point on the Earth’s surface. It is an angle measured East or West from the Prime Meridian—ranging from 0° at the Prime Meridian, to +180° Eastward and -180° Westward.
    This object contains the following parameters:
    ValueDescriptions
    latitudeA value indicating the number of degrees of latitude of the location associated with the phone number, expressed in seven decimal digits, with five decimal places. For example, 34.18264.
    longitudeA value indicating the number of degrees of longitude of the location associated with the phone number, expressed in eight decimal digits, with five decimal places For example, -118.30840.
  • metro_code
  • A 4-digit string indicating the Primary Metropolitan Statistical Area (PMSA) code for the location associated with the phone number (U.S. only). PMSA Codes are governed by the US Census Bureau. This information is useful for large metropolitan areas that comprise several smaller cities. For example, the PMSA for Long Beach, California is Los Angeles County, which gives Long Beach the PMSA Code 4480.
{
   "reference_id": "F0123456789ABCDEF0123456789ABCDE",
   "status": {
      "updated_on": "2017-02-01T14:51:28.709526Z",
      "code": 300,
      "description": "Transaction successfully completed"
   },
   "location": {
      "city": "Los Angeles",
      "county": "Los Angeles County",
      "state": "CA",
      "zip": "90066",
      "country": {
         "name": "United States",
         "iso2": "US",
         "iso3": "USA"
      },
      "time_zone": {
         "name": "America/Los_Angeles",
         "utc_offset_min": "-8",
         "utc_offset_max": "-8"
      },
      "coordinates": {
         "latitude": 33.99791,
         "longitude": -118.42302
      },
      "metro_code": "4480",   
   },
   "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"
   }
}

Request Headers

This section provides a summary of required and optional headers for a request. For details about how to use them for proper authentication, review the Authentication page. For more details about these headers, review the section Standard and TeleSign Specific Headers of the Authentication page. If you are using an SDK, you can skip ahead to the section Request Parameters.

General Headers

  • Content-Type - Required for POST requests.
  • Date - Required unless you include X-TS-Date. If you do not include the Date header value, you must mark its position with a newline character for StringToSign.

Request Headers

TeleSign-Specific HTTP Headers

  • X-TS-Date - Optional, you may use this instead of the Date header.
  • X-TS-Nonce - Optional, specifies a unique, random nonce string. You can include this header to provide additional protection against malicious replay attacks
  • X-TS-Auth-Method - Required for HMAC-SHA256.
POST https://rest-api.telesign.com/v1/phoneid/15555551212 HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Date: Tue, 31 Jan 2017 14:51:26 GMT
Content-Type: application/x-www-form-urlencoded

originating_ip=192.168.123.456&account_lifecycle_event=create

Response Headers

This section details the response entity-header and the response entity-body returned by the PhoneID Standard web service. If you choose to use one of TeleSign's SDKs, this is handled for you, so you can skip ahead to section Response Parameters.

The TeleSign server returns the following headers for this subresource:

Allow

  • Indicates the HTTP methods that the resource supports. The allowed method for v1/phoneid is POST.

Content-Type

  • Indicates the content type of the entity-body transferred in the response message. TeleSign web services always use a value of application/json.
HTTP/1.1 200 OK
Date: Wed, 01 Feb 2017 00:49:22 GMT
Server: Apache
Content-Length: 966
Allow: POST
Content-Type: application/json

Examples

This section contains a list of examples of requests and responses.

Example POST Request

POST https://rest-api.telesign.com/v1/phoneid/15555551212 HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Date: Tue, 31 Jan 2017 14:51:26 GMT
Content-Type: application/x-www-form-urlencoded

originating_ip=192.168.123.456&account_lifecycle_event=create

Example POST Response Message Header

HTTP/1.1 200 OK
Date: Wed, 01 Feb 2017 00:49:22 GMT
Server: Apache
Content-Length: 966
Allow: POST
Content-Type: application/json

Example Message Entity-body (Response)

{
   "reference_id": "F0123456789ABCDEF0123456789ABCDE",
   "status": {
      "updated_on": "2015-10-03T14:51:28.709526Z",
      "code": 300,
      "description": "Transaction successfully completed"
   },
   "location": {
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90066",
      "metro_code": "4480",
      "county": "Los Angeles County",
      "country": {
         "name": "United States",
         "iso2": "US",
         "iso3": "USA"
      },
      "coordinates": {
         "latitude": 33.99791,
         "longitude": -118.42302
      },
      "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"
   }
}

Bad Request and Error Response

POST https://rest-api.telesign.com/v1/phoneid/aaa4477012312341234 HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Date: Tue, 31 Jan 2017 14:51:26 GMT
Content-Type: application/x-www-form-urlencoded

originating_ip=192.168.123.456&account_lifecycle_event=create
HTTP/1.1 400 Bad Request
Date: Wed, 01 Feb 2017 00:49:22 GMT
Server: Apache
Content-Length: 184
Allow: POST
Content-Type: application/json
{
  "reference_id": "F0123456789ABCDEF0123456789ABCDE", 
  "status": {
     "updated_on": "2017-02-01T00:54:27.303298Z", 
     "code": 11000, 
     "description": "Invalid value for parameter phone_number."
     }
}

Country Codes and Dialing Codes

If you need to know country and dialing codes, review the Country Codes and Dialing Codes section on the Codes, Languages, Time Zones page.

Status Codes

For PhoneID, the following codes are returned for the code parameter if your transaction was a success:

Code
Description
Detail

300

Transaction successfully completed

The system was able to obtain all of the requested data for PhoneID.

301

Transaction partially completed

The system was able to obtain some of the data for PhoneID, but not all of it.

HTTP Codes Mapped to Error Codes

For a general list of HTTP codes and how they map to error codes generated by the PhoneID API, review the HTTP Codes Mapped to Error Codes section on the Codes, Languages, Time Zones page. These codes are returned for the code parameter if your transaction had issues.

Phone Number Cleansing Codes

For a general list of phone number cleansing codes review the Phone Number Cleansing Codes section on the Codes, Languages, Time Zones page.

Phone Type Codes

For a general list of phone type codes review the Phone Type Codes section on the Codes, Languages, Time Zones page.

Time Zones

For a general list of time zones you can use review the Time Zones section on the Codes, Languages, Time Zones page.

Standard PhoneID API