TMT Teleshield API specs

Download OpenAPI specification:Download

About TMT

TMT Analysis is a leading provider of data, intelligence and analytics, helping customers find extra value from the information they hold. Our team of technology and telecommunications specialists has a proven track record empowering companies, brands and agencies around the world to better understand their businesses and their customers. TMT Analysis has a suite of technology and telecommunications data available, for further information, please visit www.tmtanalysis.com or email info@tmtanalysis.com.

Data Dictionary

Field Name Data Response Description
cc ISO Country Code ISO 2 code Two (2) letter code as defined in ISO 3166-1, part of the ISO 3166 standard published by the International Organization for Standardization, to represent countries, dependent territories and special areas of geographical interest.
cic Carrier Identification Code Integer value Code that identifies the current network owner of the queried number. Mapping of the code to a network name is provided by TMT.
error or err Error Code 1 digit code:
‘0’ – No error
‘1’ – Invalid number
‘2’ – Invalid number length
‘3’ – Invalid number range
‘4’ – presence attribute not available
‘0’ – no error, valid number (correct number length, in an allocated range)
‘1’ – no country code match
‘2’ – input number has the wrong length
‘3’ – input number is not part of a range allocated to a service provider by the regulator
‘4' – input number presence is not available, other attributes will be provided where available
error_message or msg Error explanation - invalid number
- invalid number length
- invalid number range
- presence not available
Text information for the error code
etype or et Enhanced Number Type 1 or 2 digit code Code that further identifies the service type for the number range e.g., Premium rate, VoIP Telephony. List provided as Attachment 2.
iprnn International Premium Rate Number (IPRN) flag 1 digit code:
‘1’ – Yes
‘0’ - No
Code that indicates if the input TN has been detected as flagged for use to test access.
iprn_number Suspicious IPRN flag True/False Flag that indicates if the input TN has been detected as flagged for use to test access to an IPRN
iprn_number_first_seen Date yyyy/mm/dd Date that the IPRN number was first included in a list of suspicious numbers
iprn_number_last_seen Date yyyy/mm/dd Date that the IPRN number was last included in a list of suspicious numbers
iprnnd Date yyyymmdd First date that the number was noted as being available for testing access
iprnnl Date yyyymmdd Last date that the number was noted as being available for testing access
iprnr Suspicious IPRN range 1 digit code:
‘1’ – Yes
‘0’ - No
Code that indicates if the input TN has been detected as being part of the number range that has the potential to be used for fraud (e.g., Wangiri, IRSF)
iprnrd Date yyyymmdd First date that a number in the range was flagged as suspicious
iprnrl Date yyyymmdd Last date that a number in the range was flagged as suspicious
iprn_wildcard Suspicous range flag True/False Code that indicates if the input TN has been detected as being part of the number range that has the potential to be used for fraud (e.g.,Wangiri, IRSF)
iprn_wildcard_first_seen Date yyyy/mm/dd Date that an IPRN number was first included in a suspicious range
iprn_wildcard_last_seen Date yyyy/mm/dd Last date that a number in the range was noted as suspicious
itype or it Number Type 1 digit code:
‘1’ – Mobile
‘2’ - Landline
Service type for the range in which the telephone number is included.
mcc Mobile Country Code 3 digit country code A three-digit code assigned to a country that is the first part of the identity as defined in the ITU E.212 Recommendation "Land Mobile Numbering Plan". The MCC identifies the country which a mobile subscriber belongs to. In combination with the Mobile Network Code (MNC), it uniquely identifies a mobile network operator.
mnc Mobile Network Code 2 – 3 digit number used to identify a mobile network carrier Code assigned by the country regulator to identify a mobile network operator in a specific country.
msrn Mobile Station Roaming Number (MSRN) flag 1 digit code:
‘1’ – Yes
‘0’ – No
Or Ture/False
Flag for premium rate number that has been advertised as available to use for calls roaming from their home country
msrn_number_first_seen Date yyyy/mm/dd Date that the MSRN number was first included in a list of suspicious numbers
msrn_number_last_seen Date yyyy/mm/dd Date that the MSRN number was last included in a list of suspicious numbers
msrnd Date yyyymmdd First date a number was identified as being available for use as an MSRN
msrnl Date yyyymmdd Last date a number was identified as being available for use as an MSRN
network Current Carrier name Alpha-numeric value Human-readable name of the current network
nsn Network Short Name Alpha-numeric value Human-readable name of the current network
number Telephone number Input from customer Telephone number in domain name format
ocic Original Carrier Identification Code Integer value Code that identifies the original network owner of the number range in which the queried number was found. Mapping of the code to a network name is provided by TMT.
ocn Operating Company Number Company Number Four (4) character ID for North American phone companies.
omnc Original Mobile Network Code 2 – 3 digit number used to identify a mobile network carrier Code assigned by the country regulator to identify a mobile network operator in a specific country.
original network or onsn Original Network Short name Alpha-numeric value Human-readable name of the original network
ported or np Port indicator True/False/null Provides indication of whether the number has been ported
ported_date or pd Port date yyyy-mm-dd Date of last known port if applicable
ss or present Indication of whether a number is active Yes/No/na (Not available) Field that indicates whether the subscriber is present in the network e.g., is that a number has been assigned by the network operator range holder to a subscriber.
trxid Transaction id 7 character code Internally generated number for tracking of transactions
XXXXXX Random field value alphanumeric code Random field name and value to support easy implementation of additional attributes

HTTP API

POST method Teleshield

path Parameters
number
required
string

The number in E.164 format.

header Parameters
X-API-Key
required
string

The API key (obtained from https://viteza.tmtanalysis.com or from Support during customer on-boarding).

X-API-Secret
required
string

The API secret (obtained from https://viteza.tmtanalysis.com or from Support during customer on-boarding).

Responses

Response samples

Content type
application/json
{
  • "number": 376321407,
  • "cc": "AD",
  • "ocic": 376500,
  • "ocn": "",
  • "itype": 1,
  • "etype": 10,
  • "mcc": 213,
  • "omnc": 3,
  • "original_network": "Mobiland",
  • "iprn_number": false,
  • "iprn_wildcard": false,
  • "msrn": false,
  • "error": 0,
  • "trxid": "d42wkyt"
}

POST method E-Teleshield

path Parameters
number
required
string

The number in E.164 format.

header Parameters
X-API-Key
required
string

The API key (obtained from https://viteza.tmtanalysis.com or from Support during customer on-boarding).

X-API-Secret
required
string

The API secret (obtained from https://viteza.tmtanalysis.com or from Support during customer on-boarding).

Responses

Response samples

Content type
application/json
{
  • "number": 376321407,
  • "cc": "AD",
  • "ocic": 376500,
  • "ocn": "",
  • "itype": 1,
  • "etype": 10,
  • "mcc": 213,
  • "omnc": 3,
  • "original_network": "Mobiland",
  • "ported": false,
  • "cic": 376500,
  • "mnc": 3,
  • "network": "Mobiland",
  • "present": "yes",
  • "iprn_number": false,
  • "iprn_wildcard": false,
  • "msrn": false,
  • "error": 0,
  • "trxid": "XryJIIw"
}

ENUM Services

The TeleShield ENUM service includes two different response formats, each of them is accessed via a different domain. The first is based upon the standard TMT Analysis format and the second is aligned to the SIP schema. The following sub-sections describe each in detail.

TEL URI ENUM – Standard Query Example

ENUM Parameters

The parameters for the communication are:
  • Record-Type: NAPTR

  • Domain: teleshield.tmtanalysis.com

  • IPs for the service: To be provided during provisioning, referred below as TMTIP

  • Port: 53

ENUM Query format

ENUM resolution operates in the same way as a reverse DNS lookup. To perform the lookup, the E.164 number must be transformed as follows:
  • Remove non-numeric characters such as spaces, +, dashes, etc. (e.g., number “+40766-610060” needs transforming to “40766610060”).

  • Reverse the digits and add a dot between every digit (e.g., 40766610060 becomes 0.6.0.0.1.6.6.6.7.0.4)

  • Add suffix domain teleshield.tmtvelocity.com (e.g., the number now becomes 0.6.0.0.1.6.6.6.7.0.4.teleshield.tmtvelocity.com

After transforming the number, perform a DNS lookup looking for NAPTR records.

TEL URI ENUM Successful response format – Standard Query Example

A successful query will return a NAPTR Record with a tel-uri format. Example of query + result for a valid / allocated number:
$ dig +short -trace +noedns +tries=1 +time=7 -t NAPTR@TMTIP 8.1.5.2.0.4.8.7.7.6.teleshield.tmtanalysis.com

;; ANSWER SECTION

10 100 "u" "E2U+pstn:tel"
"!^(.*)$!tel:\\1;cc=sb;ocic=677501;ocn=;it=1;et=10;mcc=540;omnc=02;onsn=BMOBILE;iprnn=1;iprnnd=20211207;iprnnl=20220219;iprnr=1;iprnrd=20200305;iprnrl=20220406;msrn=0;msrnd=;msrnl=;err=0!".

TEL URI ENUM - Enhanced Query Example

$ dig +short -trace +noedns +tries=1 +time=7 -t NAPTR @TMTIP 6.3.6.5.7.2.1.2.7.0.4.eteleshield.tmtanalysis.com

10 100 "u" "E2U+pstn:tel"
"!^(.*)$!tel:\\1;cc=ro;ocic=4018720;ocn=;it=1;et=10;mcc=226;omnc=01;onsn=VODA;np=yes;pd=20130121;cic=4018760;mnc=03;nsn=COSM;ss=na;iprnn=0;iprnnd=;iprnnl=;iprnr=0;iprnrd=;iprnrl=;msrn=0;msrnd=;msrnl;err=4!" .

TEL URI ENUM – Unsuccessful Query Example

$ dig +short -trace +noedns +tries=1 +time=7 -t NAPTR @TMTIP 6.3.6.5.7.2.1.2.7.9.9.9.9.teleshield.tmtanalysis.com

  10 100 "u" "E2U+pstn:tel"
  "!^(.*)$!tel:\\1;err=1;msg=invalid_number!" .


$ dig +short -trace +noedns +tries=1 +time=7 -t NAPTR @TMTIP 9.9.6.3.6.5.7.2.1.2.7.0.4.teleshield.tmtanalysis.com

  10 100 "u" "E2U+pstn:tel"
  "!^(.*)$!tel:\\1;err=2;msg=invalid_number_length!" .


$ dig +short -trace +noedns +tries=1 +time=7 -t NAPTR @TMTIP 9.9.9.9.6.3.1.9.6.0.9.5.teleshield.tmtanalysis.com

  10 100 "u" "E2U+pstn:tel"
  "!^(.*)$!tel:\\1;err=3;msg=invalid_number_range!" .

SIP Redirect

TMT can provide support for SIP access in addition to ENUM and HTTP. The TMT SIP Redirect server provides TMT customers with real-time NP data by redirecting SIP.

Batch Service – Portal access

In addition to ENUM and HTTP query access, if you have a large volume of queries to process you can upload them via the portal and process them using the batch functionality.

The Viteza User Guide V3 Standard provides instructions on how to utilize the TeleShield batch service. It is available through TMT’s support organization (support@tmtanalysis.com).

The batch process is automated and can be accessed by clicking BATCH QUERY from Viteza portal and selecting the file that contains the numbers to be processed. To create your input file of numbers you should keep in mind the following:

  1. Input to be processed should be provided using a text file, with 1 number per query:

a. Recommended file size varies by query type – Standard and Enhanced

b. Standard – 10,000 telephone numbers

c. Enhanced – 1,000 telephone numbers

Notes:
a. If you want to submit a larger volume of input numbers please contact support for assistance.
b. When uploading a batch of numbers there is an option for adding a success orfailure URL

  1. Once a batch of numbers has been processed you will be alerted via email that processing is completed and how to get the results. If there are any issues with processing of the file, that will also be provided in an email response.

  2. Responses will be provided in a comma separated csv file. The fields returned are listed below:

Standard Query Response

Response:

  "number":
  "cc":
  "ocic":
  "ocn":
  "itype":
  "etype":
  "mcc":
  "omnc":
  "original_network":
  "iprn_number":
  "iprn_number_first_seen":
  "iprn_number_last_seen":
  "iprn_wildcard":
  "iprn_wildcard_first_seen":
  "iprn_wildcard_last_seen":
  "msrn":
  "msrn_first_seen":
  "msrn_last_seen":
  "error":
  "trxid":

Example:

  {"number":37067890694,"cc":"LT","ocic":370503,"ocn":"","itype":1,"etype":10,"mcc":"246","omnc":"03","original_network":"Tele2","iprn_number":true,"iprn_number_first_seen":"2022/03/05","iprn_number_last_seen":"2022/03/05","iprn_wildcard":true,"iprn_wildcard_first_seen":"2022/03/05","iprn_wildcard_last_seen":"2022/03/05","msrn":true,"msrn_first_seen":"2022/03/05","msrn_last_seen":"2022/03/05","error":0,"trxid":"r321JE9"}

Enhanced Query Response

Response:

  "number":
  "cc":
  "ocic":
  "ocn":
  "itype":
  "etype":
  "mcc":
  "omnc": 
  "original_network":
  "ported":
  "ported_date":
  "cic":
  "mnc":
  "network":
  "present":
  "iprn_number":
  "iprn_number_first_seen":
  "iprn_number_last_seen":
  "iprn_wildcard":
  "iprn_wildcard_first_seen":
  "iprn_wildcard_last_seen":
  "msrn":
  "msrn_first_seen":
  "msrn_last_seen":
  "error":
  "trxid":
  "XXXX":

Example:

  {"number": 37067890694, "cc": "LT", "ocic": 370503, "ocn": "", "itype": 1, "etype":10, "mcc": "246", "omnc": "03", "original_network": "Tele2", "ported": true,"ported_date": "2020-05-16", "cic": 370503, "mnc": "03", "network": "Tele2","present": "no", "iprn_number": true, "iprn_number_first_seen": "2022/03/05","iprn_number_last_seen": "2022/03/05", "iprn_wildcard": true,"iprn_wildcard_first_seen": "2022/03/05", "iprn_wildcard_last_seen": "2022/03/05","msrn": true, "msrn_first_seen": "2022/03/05", "msrn_last_seen": "2022/03/05","error": 0, "trxid": "F2y9ITF"}

Failed Query Examples

    {"number":9999721275636,"error":1,"error_message":"invalid number"}


    {"number":4072127563699,"error":2,"error_message":"invalid number length"}


    {"number":590691369999,"error":3,"error_message":"invalid number range"}

Operator files

For each country provisioned, an ‘operators’ file is provided during the provisioning process. Whenever changes occur in the list of operators for a provisioned country, an update is sent by TMT Analysis support to our customers with the revised ‘operators’ file.

  1. For all countries except the US and Canada, the files contain the following fields, separated by “;”:
  • Service provider ID – unique across the system, TMT assigned. You will find this in the download files as well as in the ‘cic’ field of the ENUM response. This is the field you should use for mapping to your system.
  • Network Short name – unique per country. This can be identified in the download files as well as in the ‘cn’ field of the ENUM response. This field is for quickly identifying networks during operator-assisted tests.
  • Network Full name – the full name of the operator.
  • MCC – Mobile Country Code
  • MNC – Mobile Network Code

Example:

filename SK_operators.csv

  4219920;SKOTW;O2 Slovakia;231;06
  4219910;SKOGE;Orange Slovakia;231;01
  4219900;SKTEL;Slovak Telekom;231;02
  4219903;SKSWA;Swan 4KA Slovakia;231;03
  4219930;SKZSR;ZSR Slovakia;231;99
  1. For the United States and Canada the set-up is different. The SPID (Service Provider ID) is also used as the OCN (Operating Company Name) as is:
  • SPID (this is the same as the OCN)
  • OCN Name – provided by the US data supplier.

TeleShield Service Types

Service Type i type e type
Audio Text 2 1
Calling Cards 2 2
Electronic Services 2 3
Freephone 2 4
Geographic 2 5
Intermodal Numbers (FIX<->MOB porting) 2 6
Internet Service Provider 2 7
Local Rate 2 8
Machine to Machine 1 9
Mobile 1 10
Mobile (CDMA) 1 11
Mobile to Mobile 1 12
National Geographic 2 13
National Rate 2 14
Non intermodal CC (Portability =Y) 2 15
Paging 1 16
Payphone 2 17
Personal 1 18
Prefix Type Unknown (Portability =N) 2 19
Premium Rate 2 20
Routing Code 2 21
Satellite 1 22
Shared Cost 2 23
Short Codes Commercial 2 24
Specialized Mobile Radio 1 25
Telegram 2 26
Universal Access 2 27
Videotex 2 28
Virtual Private Network 2 29
Voicemail (geographic) 2 30
Voicemail (mobile) 1 31
VoIP Telephony 2 32
Wireless geographic 1 33
  • e type – is the range type encoded from 1 to 33.
  • i type – the type encoded - 1 is mobile; 2 is landline
  • Can be fixed or non-fixed. Fixed VoIP is an Internet based phone line associated with a physical address. Non-fixed VoIP phone lines are not associated with a physical address e.g., Google voice and Skype.