TMT Teleshield API specs

Download OpenAPI specification:Download

TMT Support: support@tmtid.com URL: https://www.tmtid.com Terms of Service

Version history

v1.0 - September 2021

Baseline

v1.1 - February 2022

Coverage update

v1.2 - April 2022

Data enhancement to provide flag and first seen date for suspicious international premium and mobile station roaming numbers, and associated number ranges

v1.3 - May 2022

Inclusion of last seen date for suspicious international premium and mobile station roaming numbers, and associated suspicious number ranges

v2.0 - August 2023

Update of the TeleShield queries available to include Routing, Fraud and Enhanced Fraud use cases.
Introduction of TeleShield Score and TeleShield Level Assessment in Fraud and Enhanced Fraud query responses.
Added error 254 for querying destinations banned on customer’s demand.
Added OOCN, OMCC to all plan packages.
Applicable to TeleShield Enhanced only: addition of errors 4, 5 (related to the Number Portability and Subscriber Status coverage).

About TMT

TMT ID 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 ID has a suite of technology and telecommunications data available, for further information, please visit www.tmtid.com or email info@tmtid.com.

TMT TeleShield v2.0 Overview

Telecommunications fraud is a global issue that has become even more pervasive with the growth in IP telephony and Voice over IP (VoIP) providers. It costs service providers and their customers billions of dollars annually. The TMT TeleShield service enables companies to take control of their strategy to win against fraudsters.

With our TeleShield products, companies can ‘shield’ themselves from incurring losses from telephony fraud schemes. TMT provides unique access to real-time data through a robust network of suppliers combined with its own SS7 infrastructure enabling us to provide responses when other suppliers may be blocked by a network operator.

TeleShield provides intelligence on telephone numbers which can identify suspicious activity and enable service providers to make informed decisions to avoid financial impact or negative customer experience. For example, TeleShield provides information on:

Has the number been made available for service by the regulator?
Does the number have a suspicious service type, for example is it a premium rate, satellite or VoIP?
Has the number been assigned to a subscriber by a service provider?
Has the number been ported?

Key features

Coverage for more than 240 countries/territories worldwide
Flexible access methods to support your needs (e.g., ENUM, HTTP, Batch)
Real-time and porting information available as an option
Geographically redundant query sites
Continuously updated data - number range and portability information

TeleShield Query Types:

To address market needs, the TeleShield service provides 3 query types to support defined use cases:

Routing Use Case - provides information to determine whether a telehpone number is invalid so a call/message should not be sent to a telephone number:
- Identify valid numbers - number is part of a range that has been allocated to a service provider and is the correct format/length,
- Confirm detailed service type (e.g., mobile/fixed) and up to 30+ additional service clarifications (e.g., premium, VoIP, satellite, M2M, free phone, toll free, etc.).
Fraud Use Case – in addition to the information provided in the Routing query response, provides information designed to determine if a number has a proposentity to be use in a fraud scheme.. It is designed for price-sensitive fraud use case solutions and includes telephone number attributes to:
- Identify International Premium Rate Numbers (IPRNs)
- Identify suspicious number ranges
- Provide TeleShield Score and TeleShield Level Assessment for a number to have a propensity to be fraudulent
Enhanced Fraud Use Case – includes the attributes returned from the Routing and Fraud use case responses plus information from real-time network queries that provides data to:
- Confirm if the number has been assigned to a subscriber
- Identify current service provider
- IndIcate if the number has been ported
- Confirm last port date where available

Parameter	TeleShield Routing	TeleShield Fraud	TeleShield Enhanced Fraud
Identification if a number is valid	x	x	x
Identification if a number has a valid length	x	x	x
Identification if a number is part of an allocated range	x	x	x
Identification if a number is Mobile or Fixed (itype)	x	x	x
Additional number identification type (etype)	x	x	x
Country Code (CC)	x	x	x
Original Carrier MNC, MCC, OCN, CIC, Name	x	x	x
TeleShield Score assessment (TS)		x	x
TeleShield Level assessment (TL)		x	x
International Premium Rated Number (IPRN) Flag		x	x
First and Last time a number was seen in the IPRN list		x	x
International Premium Rated Number Suspicious Range Flag		x	x
The First and the Last time a number was included in a suspicious range		x	x
Mobile Station Roaming Number (MSRN) Flag		x	x
First and Last time a number was seen in MSRN list		x	x
Subscriber Status / Presence			x
Identification if a number was ported			x
Ported Date			x
Current Carrier Data (MNC, MCC, OCN, CIC, Name)			x

Data Dictionary v2.0

Output Data description

Field Name (Http api)	Field Name (Enum)	HTTP API Response	Description
Field Name (Http api)	Field Name (Enum)	ENUM Response	Description
cc	cc	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	cic	Integer value	Current Carrier Identification Code. It Identifies the current network owner of the queried number. Mapping of the code to a network name is provided by TMT
error	err	Values: 0, 1, 2, 3, 4, 5, 254	‘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 '5' – (presence not available) input number presence and portability are not available. Ported and Ported date fields will be hidden in query response. '254' – (no auth) queried destination was blocked as customer requested.
error_message	msg	invalid number invalid number length invalid number range presence not available no auth	Text information for the error codes.ENUM queries are filtered by firewalls.
error_message	msg	invalid_number invalid_number_length invalid_number_range
etype	et	Values: [1 – 33]	Code that further identifies the service type for the number range e.g., Premium rate, VoIP Telephony. List provided as Attachment 2.
itype	it	1 – mobile 2 – landline (fixed)	Service type for the range in which the telephone number is included.
iprn_number	iprnn	yes / no	Value that indicates if the input phone number has been detected as flagged for use to test access.
iprn_number	iprnn	1 / 0
iprn_number_first_seen	iprnnd	yyyy/mm/dd	Date that the IPRN number was first included in a list of suspicious numbers
iprn_number_first_seen	iprnnd	yyyymmdd
iprn_number_last_seen	iprnnl	yyyy/mm/dd	Date that the IPRN number was last included in a list of suspicious numbers
iprn_number_last_seen	iprnnl	yyyymmdd
iprn_wildcard	iprnr	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	iprnr	1 / 0
iprn_wildcard_first_seen	iprnrd	yyyy/mm/dd	First date that a number in the range was flagged as suspicious
iprn_wildcard_first_seen	iprnrd	yyyymmdd
iprn_wildcard_last_seen	iprnrl	yyyy/mm/dd	Last date that the number was noted as being available for testing access
iprn_wildcard_last_seen	iprnrl	yyyymmdd
mcc	mcc	3 – digit number	Current Carrier Mobile Country Code.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	mnc	2 – 3-digit number used to identify a mobile network carrier	Current Carrier Mobile Network Code.Code assigned by the country regulator to identify a mobile network operator in a specific country.
msrn	msrn	true / false	Mobile Station Roaming Number.Flag for premium rate number that has been advertised as available to use for calls roaming from their home country.
msrn	msrn	1 / 0
msrn_number_first_seen	msrnd	yyyy/mm/dd	Date that the MSRN number was first included in a list of suspicious numbers
msrn_number_first_seen	msrnd	yyyymmdd
msrn_number_last_seen	msrnl	yyyy/mm/dd	Date that the MSRN number was last included in a list of suspicious numbers
msrn_number_last_seen	msrnl	yyyymmdd
network	nsn	Alpha-numeric value	Current Network Short Name
number	n/a	Input from customer	Queried phone number
ocic	ocic	Integer value	Original Carrier Identification Code. It Identifies the original network owner of the queried number. Mapping of the code to a network name is provided by TMT.
ocn	ocn	Integer value	Current Carrier Operating Company Number.Four (4) character ID for North American phone companies.
omcc	omcc
omnc	omnc	2 – 3 digit number	Code assigned by the country regulator to identify a mobile network operator in a specific country.
oocn	oocn		Current Carrier Operating Company Number.Four (4) character ID for North American phone companies.
original network	onsn	Alpha-numeric value	Original Network Short Name
ported	np	true / false / null	Provides indication of whether the number has been ported
ported	np	1 / 0	Provides indication of whether the number has been ported
ported_date	pd	yyyy-mm-dd	Date of last known port if applicable
ported_date	pd	yyyymmdd	Date of last known port if applicable
present	ss	yes / no / na	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.
present	ss	1 / 0 / na
status		2	Status 2 Is received for wrong input of apikey or apisecret.
status_message		Service or destination not authorized.	Text information for the status.
tl	tl	L M H	TeleShield Level Field that converts the TeleShield Score into an assessment level for the number to have a propensity to be used in a fraud scheme: L (Low) <20 M (Medium) >=20 & <50 H (High) >= 50
ts	ts	Values: [0 – 100]	TeleShield Score The result of the application of a consistent set of rules to publicly available number intelligence data. The relevant attributes are assigned a number that reflects the possibility for it to be fraudulent e.g., number format, suspicious number type, suspicious IPRN/MSRN number instance, suspicious range, port attributes and subscriber status.
trxid		7 character code	Transaction ID Internally generated number for tracking of transactions.
XXXXXX	xxxxxx	Alphanumeric values	Anonymized information

Etypes values description

Service Type	i type	e type	Description
Audio Text	2	1	A specific category of Interactive Voice Response (IVR) services to provide incoming callers with information and services using an automated script.
Calling Cards	2	2	Numbers that are associated with providers of pre-paid domestic and international calling cards. In many countries these may fall into other categories such as non-geographic numbers, but some countries created specific numbering ranges for their use.
Electronic Services	2	3	– A type that is only used in a small number of countries, and for a variety of use cases. For example, in Italy this type is assigned to ‘SMS/MMS and data transmission services’ whilst in Mozambique and Nigeria the regulator describes Electronic Services as electronic fax services.
Freephone	2	4	Tollfree, number where the called party pays for the cost of the call not the calling party (e.g., 1-800 numbers).
Geographic	2	5	Most generic consumer landline/wireline services are described as geographic, where typically an area code is used for specific regions.
Intermodal Numbers (FIX<->MOB porting)	2	6	– These number ranges are reserved for \ support of porting of fixed numbers to mobile.
Internet Service Provider	2	7	Numbers reserved for ISPs who may historically have offered services such as ‘one number’ or ‘personal number’ type services where a number would often be terminated over an Internet connection and the provider can sell voice, data, and broadband to the customer as a ‘triple play’ proposition.
Local Rate	2	8	Numbers that can be assigned non-geographically but are always billed to the calling party at the same rate as a local call, regardless of the location of the calling party in that country.
Machine to Machine	1	9	Any network device communication to another network device over mobile or landline numbers. Number ranges that are reserved for Internet of Things (IoT) types of services to denote that they do not belong to human subscribers.
Mobile	1	10	Standard code to signify most mobile telephones on a global basis to support wireless communication.
Mobile (CDMA)	1	11	Used in some countries where certain network operators use the Code Division Multiple Access technology for 2G and 3G wireless as opposed to the more common GSM (Global System for Mobiles) technology. Type 11 and Type 10 should be considered interchangeable in terms of functionality experienced by the subscriber.
Mobile to Mobile	1	12	Same as type 9. Electronic services for automated applications.
National Geographic	2	13	Another variation of Type 6 numbers where specific codes denotes geographical regions.
National Rate	2	14	Non-geographically coded landline numbers that are charged as a national call regardless of the location of the calling party.
Non intermodal CC (Portability =Y)	2	15	Blocks can be fixed or mobile, but porting between fixed and mobile numbers is not supported.
Paging	1	16	Number ranges specifically allocated to paging devices.
Payphone	2	17	Many countries simply use standard landline geographical numbers (e.g., Type 5) for payphone kiosks however some countries choose to allocate specific ranges for them.
Personal	1	18	Number ranges specifically reserved for service providers who offer some kind of personal numbering service (i.e., one single number that can be assigned to landline, mobile or IP node).
MSRN	1	19	Mobile Station Roaming Number
Premium Rate	2	20	Landline numbers where the calling party pays more than standard local or national rates, often with a proportion of the costs going to the registered owner of the number. Depending upon the country various price bands may exist within the allocated Premium rate ranges.
Routing Code	2	21	This is a designation given by the global authorities but there are no ranges in the source data currently allocated this type.
Satellite	1	22	Number ranges reserved for Satellite telephones.
Shared Cost	2	23	Specific landline ranges where the cost of making the call is shared between the calling and called party. This can operate in the same way as Local or National rate numbers, or the share of the cost may be different.
Short Codes Commercial	2	24	Specific numbers that are shorter than the regular dial plan ranges and are specifically sold to businesses that require either a more memorable number (such as NHS 111 in the UK) or easy-to-use number. Not available in all countries.
Specialized Mobile Radio	1	25	Number ranges reserved for specialized mobile radio (SMR) devices.
Telegram	2	26	Number ranges used as part of the long-distance telegraphy network. Almost none are still in use today.
Universal Access	2	27	Number ranges reserved for Universal Access initiatives (often to increase penetration of phone usage in underdeveloped countries).
Videotex	2	28	Similar in nature to Type 1 but with the additional capability to share images and video messaging.
Virtual Private Network	2	29	Number ranges that are allocated to providers of VPN services.
Voicemail (geographic)	2	30	Number ranges allocated to voicemail providers for hosting their mailboxes. Geographic voicemail tends to be associated with landline services (such as remote call forwarding and answering/concierge services).
Voicemail (mobile)	1	31	Number ranges for voicemail operators that offer automatic forwarding, answering and message retrieval services for mobile voicemail.
VoIP Telephony	2	32	Specific ranges for providers of VoIP services to allow incoming calls from the regular telephony network. Where they exist VoIP number ranges are typically assigned to fixed networks, since they can then provide compliance with geographical rules on emergency services provision etc.
Wireless geographic	1	33	Special category of mobile telephone numbers that are coded based upon their region.

HTTP API v2.0

TeleShield Routing

path Parameters

number

required

string

The number in E.164 format (includes the country code sufix).

header Parameters

X-API-Key required	string Your apikey (delivered via email).
X-API-Secret required	string Your apisecret (delivered via email).

Responses

Response samples

Content type

application/json

Example

TeleShield Routing Successful Command and Response Example

{"number": 40766610060,
"cc": "RO",
"ocic": 4018760,
"oocn": null,
"itype": 1,
"etype": 10,
"omcc": "226",
"omnc": "03",
"original_network": "Telekom Romania Mobile (Cosmote)",
"error": 0,
"trxid": "Pp2dxrl"
}

TeleShield Fraud

path Parameters

number

required

string

The number in E.164 format (includes the country code sufix).

header Parameters

X-API-Key required	string Your apikey (delivered via email).
X-API-Secret required	string Your apisecret (delivered via email).

Responses

Response samples

Content type

application/json

Example

TeleShield Fraud Successful Command and Response Example

{"number": "247490XX",
"cc": "AC,",
"ocic": 247501,
"oocn": null,
"itype": 1,
"etype": 10,
"omcc": "658",
"omnc": "01",
"original_network": "Sure South Atlantic",
"iprn_number": true,
"iprn_number_first_seen": "2023-02-07",
"iprn_number_last_seen": "2023-02-07",
"iprn_wildcard": true,
"iprn_wildcard_first_seen": "2023-02-07",
"iprn_wildcard_last_seen": "2023-06-20",
"msrn": true,
"msrn_first_seen": "2023-02-07",
"msrn_last_seen": "2023-02-07",
"ts": 25,
"tl": "M",
"error": 0,
"trxid": "u621Kb3"
}

TeleShield Enhanced Fraud

path Parameters

number

required

string

The number in E.164 format (includes the country code sufix).

header Parameters

X-API-Key required	string Your apikey (delivered via email).
X-API-Secret required	string Your apisecret (delivered via email).

Responses

Response samples

Content type

application/json

Example

TeleShield Fraud Successful Command and Response Example

{"number": 40766610060,
"cc": "RO",
"ocic": 4018760,
"oocn": null,
"itype": 1,
"etype": 10,
"omcc": "226",
"omnc": "03",
"original_network": "Telekom Romania Mobile (Cosmote)",
"ported": false,
"ported_date": "2017-11-23",
"cic": 4018760,
"ocn": "",
"mcc": 226,
"mnc": 3,
"network": "Telekom Romania Mobile (Cosmote)",
"present": "yes",
"iprn_number": false,
"iprn_wildcard": false,
"msrn": false,
"ts": 0,
"tl": "L",
"error": 0,
"trxid": "Q4iRYrT"
}

ENUM TeleShield Routing v2.0

ENUM TeleShield Routing Successful Command and Answer:

Command:
dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 0.6.0.0.1.6.6.6.7.0.4.r-teleshield.tmtid.com

Answer:
10 100 "u" "E2U+pstn:tel"
"!^(.*)$!tel:\\1;cc=ro;ocic=4018760;oocn=;it=1;et=10;omcc=226;omnc=03;onsn=COSM;err=0

ENUM TeleShield Routing error response for invalid number formats:

Input number has no Country Code match.

 Command:
 dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 9.9.9.9.9.9.r-teleshield.tmtid.com

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

Input number has the wrong length.

 Command:
 dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 4.2.0.7.5.2.2.7.0.4.r-teleshield.tmtid.com

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

Input number is not part of an allocated range from the regulator.

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 7.3.8.5.7.8.5.9.9.0.4.r-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;err=3;msg=invalid_number_range!".

ENUM – TeleShield Routing error response for Unauthorized Access

The output status is NXDOMAIN and the answer section is blank.

ENUM TeleShield Fraud v2.0

ENUM TeleShield Fraud Successful Command and Answer:

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 7.2.7.6.5.2.3.5.4.3.1.f-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;cc=ky;ocic=1345505;oocn=;it=1;et=10;omcc=346;omnc=050;onsn=DIGICEL;ts=15;tl=L;iprnn=1;iprnnd=20221006;iprnnl=20230620;iprnr=1;iprnrd=20221006;iprnrl=20230620;msrn=0;msrnd=;msrnl=;err=0!"

ENUM TeleShield Fraud error response for invalid number formats:

The TeleShield Score and TeleShield Level of assessment for the number to be part of a fraud scheme are set to the highest level. See examples below:

Input number has no Country Code match.

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 9.9.9.9.9.9.f-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;ts=100;tl=H;err=1;msg=invalid_number!".

Input number has the wrong length.

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 4.2.0.7.5.2.2.7.0.4.f-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;ts=100;tl=H;err=2;msg=invalid_number_length!".

Input number is not part of an allocated range from the regulator.

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 7.3.8.5.7.8.5.9.9.0.4.f-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;ts=100;tl=H;err=3;msg=invalid_number_range!".

ENUM – TeleShield Fraud error response for Unauthorized Access

The output status is NXDOMAIN and the answer section is blank.

ENUM TeleShield Enhanced Fraud v2.0

ENUM TeleShield Enhanced Fraud Successful Command and Answer:

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 7.2.7.6.5.2.3.5.4.3.1.e-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;cc=ro;ocic=4018760;oocn=;it=1;et=10;omcc=226;omnc=03;onsn=COSM;np=no;pd=20171123;cic=4018760;ocn=;mcc=226;mnc=03;nsn=COSM;ss=yes;ts=0;tl=L;iprnn=0;iprnnd=;iprnnl=;iprnr=0;iprnrd=;iprnrl=;msrn=0;msrnd=;msrnl=;err=0!"

ENUM TeleShield Enhanced Fraud error response for invalid number formats:

The TeleShield Score and TeleShield Level of assessment for the number to be part of a fraud scheme are set to the highest level. See examples below:

Input number has no Country Code match.

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 9.9.9.9.9.9.e-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;ts=100;tl=H;err=1;msg=invalid_number!".

Input number has the wrong length.

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 4.2.0.7.5.2.2.7.0.4.e-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;ts=100;tl=H;err=2;msg=invalid_number_length!".

Input number is not part of an allocated range from the regulator.

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 7.3.8.5.7.8.5.9.9.0.4.e-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;ts=100;tl=H;err=3;msg=invalid_number_range!".

NOTE: Two additional Error scenarios are possible based on the availability of the two supplementary real-time network calls (NP and Presence).

Available Number Portability (np) / Unavailable Presence.

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 4.4.0.0.0.0.0.1.0.7.4.3.2.e-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;cc=uz;ocic=998505;oocn=;it=1;et=11;omcc=434;omnc=08;onsn=UZBEKTELE;np=no;pd=;cic=998505;ocn=;mcc=434;mnc=08;nsn=UZBEKTELE;ss=na;ts=0;tl=L;iprnn=0;iprnnd=;iprnnl=;iprnr=0;iprnrd=;iprnrl=;msrn=0;msrnd=;msrnl=;err=4!"

Unavailable Number Portability (np) / Unavailable Presence.

Note: In this case Ported and Ported Date fields are hidden.

Command: dig +short +noedns +tries=1 +time=7 -t NAPTR @195.181.168.240 2.0.3.8.7.0.4.4.0.3.2.9.e-teleshield.tmtid.com Answer: 10 100 "u" "E2U+pstn:tel" "!^(.*)$!tel:\\1;cc=pk;ocic=92500;oocn=;it=1;et=10;omcc=410;omnc=01;onsn=JAZZ-MOBILINK;np=na;pd=;cic=92500;ocn=;mcc=410;mnc=01;nsn=JAZZ-MOBILINK;ss=na;ts=0;tl=L;iprnn=0;iprnnd=;iprnnl=;iprnr=0;iprnrd=;iprnrl=;msrn=0;msrnd=;msrnl=;err=5!".

ENUM – TeleShield Enhanced Fraud error response for Unauthorized Access

The output status is NXDOMAIN and the answer section is blank.

Data Dictionary v1.3

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 v1.3

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.tmtid.com or from Support during customer on-boarding).
X-API-Secret required	string The API secret (obtained from https://viteza.tmtid.com or from Support during customer on-boarding).

Responses

Response samples

200

Content type
application/json

Example
Successful response format

{"number": 376321407, "cc": "AD", "ocic": 376500, "ocn": null, "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.tmtid.com or from Support during customer on-boarding).
X-API-Secret required	string The API secret (obtained from https://viteza.tmtid.com or from Support during customer on-boarding).

Responses

Response samples

200

Content type
application/json

Example
Successful response format

{"number": 376321407, "cc": "AD", "ocic": 376500, "ocn": null, "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 v1.3

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 ID 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.tmtid.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.tmtid.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.tmtid.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.tmtid.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.tmtid.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.tmtid.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, HTTP and SIP query access, if you have a large volume of queries to process you can upload them via the Viteza Customer Portal and process them using the batch functionality.
The batch process is automated and can be accessed by clicking BATCH QUERY (here) and uploading the file that contains the numbers to be processed. The Batch limit size for TeleShield service is: 300,000 numbers/file.
Once a batch of numbers has been processed you will be notified 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.
Responses will be provided in JSON format in a comma separated txt file. The fields returned are listed below:

[ { "number": 24749060, "cc": "AC", "ocic": 247501, "oocn": null, "itype": 1, "etype": 10, "omcc": "658", "omnc": "01", "original_network": "Sure South Atlantic", "iprn_number": true, "iprn_number_first_seen": "2023-02-07", "iprn_number_last_seen": "2023-02-07", "iprn_wildcard": true, "iprn_wildcard_first_seen": "2023-02-07", "iprn_wildcard_last_seen": "2023-06-20", "msrn": true, "msrn_first_seen": "2023-02-07", "msrn_last_seen": "2023-02-07", "ts": 25, "tl": "M", "error": 0, "trxid": "u621Kb3"} { "number": 9999721275636, "ts": 100, "tl": "H", "error": 1, "error_message": "invalid number"} { "number": 4072127563699, "ts": 100, "tl": "H", "error": 2, "error_message": "invalid number length"} { "number": 590691369999, "ts": 100, "tl": "H", "error": 3, "error_message": "invalid number range"} ]

Operator files

Global coverage for 240 countries/territories is provided. For each country, an operators file is provided during the provisioning process via email.
The up-to-date coverage files are updated in the Viteza Customer Portal

network_id – unique across the system (assigned by TMTID). You will find this in the download files as well as in the CIC field of the ENUM response. You should use this field for mapping to our system.

ocn – (only for US/Canada files) – Operating Company Name is the carrier’s Company Code. It is assigned by the National Exchange Carrier Association. You should use this field for mapping to our system.

network – carriers’ short name. Unique per country. You will find this 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.

full_name – the full name of the operator/carrier.

mcc – the mobile country code of the operator/carrier.

mnc – mobile network code for the operator/carrier.

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

Developers – TeleShield

TMT Teleshield API specs

Version history

v1.0 - September 2021

v1.1 - February 2022

v1.2 - April 2022

v1.3 - May 2022

v2.0 - August 2023

About TMT

TMT TeleShield v2.0 Overview

Key features

TeleShield Query Types:

Data Dictionary v2.0

Output Data description

Etypes values description

HTTP API v2.0

TeleShield Routing

path Parameters

header Parameters

Responses

Response samples

TeleShield Fraud

path Parameters

header Parameters

Responses

Response samples

TeleShield Enhanced Fraud

path Parameters

header Parameters

Responses

Response samples

ENUM TeleShield Routing v2.0

ENUM TeleShield Fraud v2.0

ENUM TeleShield Enhanced Fraud v2.0

Data Dictionary v1.3

HTTP API v1.3

POST method Teleshield

path Parameters

header Parameters

Responses

Response samples

POST method E-Teleshield

path Parameters

header Parameters

Responses

Response samples

ENUM Services v1.3

TEL URI ENUM – Standard Query Example

ENUM Parameters

ENUM Query format

TEL URI ENUM Successful response format – Standard Query Example

TEL URI ENUM - Enhanced Query Example

TEL URI ENUM – Unsuccessful Query Example

SIP Redirect

Batch Service – Portal access

Operator files

What Our Customers Are Saying

Ready to get started?