Technical Guide. REST API for Number Information Services

Transcription

1 Technical Guide REST API for Number Information Services Munich Singapore London San Francisco

2 Table of Contents Page 1. Introduction 3 2. Authentication 3 3. Number Information Servies Query Information on Phone Number Synchronous vs Asynchronous Responses Global Number Portability Global Number Verification HTTP Status Codes 11 2

3 1. Introduction Basic example to resolve Global Number Portability (GNP): curl -u username:password -X GET The REST API (Representational State Transfer Application Programming Interface) enables quick and easy access to tyntec s Number Information Services (NIS). The communication is established via HTTPS (Hypertext Transfer Protocol Secure) connections. The exchanged object type is JSON (JavaScript Object Notation). tyntec s application accepts and replies with "application/json" as "Content-Type" (and "charset=utf-8") in the HTTP header. All of tyntec s Number Information Services are accessible through the base URL (Unique Resource Location) (${baseurl}): 2. Authentication tyntec will provide a username (${username}) and password (${password}) to grant access to the services: The Base64-encoded combination "${username}:${password}" is used as an authentication-token for the Basic HTTP authentication and can also be given in the HTTP header: Authorization: Basic ${authentication-token} 3

4 3. Number Information Services The Global Number Portability service returns information on the subscription network (MCC MNC) based on the MSISDN. The Global Number Verification service returns information on the number range holder, the IMSI (International Mobile Subscriber Identity), the subscription network, and the servicing network. The number information is provided at best effort. In case a response does not contain all fields listed in this guide, the respective information could not be retrieved. 3.1 Query Information on a Phone Number The number information on a specific MSISDN (Mobile Station International Subscriber Directory Number) can be queried from two resources: Service Global Number Portability Global Number Verification Resource URL ${baseurl}/gnp ${baseurl}/gnv Method GET GET Table 1: tyntec resource URLs for Number Information Services. The MSIDN is provided in the respective parameter:?msisdn=$msisdn In this case, tyntec s application will return the requested number information on the given MSISDN ($msisdn). tyntec s application server performs a consistency check on the provided MSISDN and callbackurl before processing the request in order to prevent avoidable consts due to malformed requests. 4

5 3.2 Synchronous vs Asynchronous Responses The time needed to retrieve number information is typically around ~350 ms. But sometimes it can take up to several seconds to receive the number information, e.g., when operators respond very slowly. Therefore, tyntec s number information services can be queried for a synchronous or asynchronous response. The default response is synchronous and the requested number information is given in the body of the HTTP 200 OK response of tyntec s application server. The asynchronous response can be triggered with the request parameter:?callbackurl=$callbackurl In this case, tyntec s application will POST the requested number information to your webserver at the given URL ($callbackurl). tyntec s application will retry for a maximum of 48 hours to POST the number information after 1, 5, 10, 20, 30, 60 minutes if your server does not answer 200 OK within 2 seconds. 3.3 Global Number Portability The following code blocks give examples of how to query number information on a MSISDN. Example for Query GNP (synchronous response): curl -u username:password -X GET -H "Accept: application/json" Example for Query GNP (asynchronous response): curl -u username:password -X GET -H "Accept: application/json" 5

6 Response to Query GNP containing the requested number information: { "requestid":"12-86cfafba-8677-f42b-5050-ece6af6abf01", "msisdn":" ", "mcc":"262", "mnc":"02", "ttid":15, "operator":" Vodafone", "country":"deu", "timezone":"+0100", "technology":"gsm", "ported":"false", "price":0.001, "currency":"eur", "priceeffective":" t00:00: ", "errorcode":"0" } In this request there are a number of parameters that need to be defined, others are optional: Parameter Possible Values Description requestid msisdn MCC MNC ttid operator country timezone technology UUID according to RFC 4122 phone number according to ITU E.164 integer country code following ISO alpha-3 +HH:mm (according to ISO 8601) The unique identifier provided for each request. The phone number of interest given in international format. A representative MCC (Mobile Country Code) of the operator. A representative MNC (Mobile Network Code) of the operator. The tyntec id of the operator. The mapping can be found in the Customer Lounge under Home>Resource Center>Network Lists>Mobile Outbound SMS ( The human readable name of the operator. The three-letter county code where the operator is located. The operator s local time zone relative to UTC. The technology (see table at the end of document) used by the operator s network. 6

7 ported price currency priceeffective boolean float currency code following ISO 4217 date in the format yyyy-mmddthh:mm:ss (according to ISO 8601) An indication of the porting status (yes/no). The price for the query. The currency in which the pricing is given; corresponding to the currency of the invoice. The date when the price became effective. errorcode Possible values for errorcode can be found in the document Error Codes. 3.4 Global Number Verification The following code blocks give examples of how to query number information on a MSISDN. Example for Query GNV (synchronous response): curl -u username:password -X GET -H "Accept: application/json" Example for Query GNV (asynchronous response): curl -u username:password -X GET -H "Accept: application/json" 7

8 Response to Query GNV containing the requested number information: { "requestid":"12-86cfafba-8677-f42b-5050-ece6af6abf01", "msisdn":" ", "nrhmcc":"262", "nrhmnc":"02", "nrhttid :15, "nrhoperator":"vodafone", "nrhcountry":"deu", "nrhtimezone":"+0100", "nrhtechnology":"gsm", "imsimcc":"262", "imsimnc":"02", "imsittid":15, "imsioperator":"vodafone", "imsicountry":"deu", "imsitimezone":"+0100", "imsitechnology":"gsm", "hlrcc":"49", "hlrndc":"162", "hlrmcc":"262", "hlrmnc":"02", "hlrttid":"15, "hlroperator":"vodafone", "hlrcountry":"deu", "hlrtimezone":"+0100", "hlrtechnology":"gsm", "msccc":"49", "mscndc":"162", "mscmcc":"262", "mscmnc":"02", "mscttid":15, "mscoperator":"vodafone", "msccountry":"deu", "msctimezone":"+0100", "msctechnology":"gsm", "ported":"false", "roaming":"false", "presence":"true ", "price":0.001, "currency":"eur", "priceeffective":" t00:00: ", "errorcode":"0", } 8

9 In this request there are a number of parameters that need to be defined, others are optional: Parameter Possible Values Description requestid msisdn nrhmcc nrhmnc nrhttid nrhoperator nrhcountry nrhtimezone nrhtechnology imsimcc imsimnc imsittid imsioperator imsicountry imsitimezone imsitechnology hlrcc hlrndc UUID according to RFC 4122 phone number according to ITU E.164 integer country code following ISO alpha-3 +HH:mm (according to ISO 8601) integer country code following ISO alpha-3 +HH:mm (according to ISO 8601) according to ITU E.214 according to ITU E.214 The unique identifier provided for each request. The phone number of interest given in international format. A representative MCC (Mobile Country Code) of the NRH s network (Number Range Holder). A representative MNCs (Mobile Network Codes) of the NRH s network. The tyntec operator id of the NRH. The mapping can be found in the Customer Lounge under Home>Resource Center>Network Lists>Mobile Outbound SMS ( Human readable name of the NRH. The three-letter county code where the NRH s network is located. Local time zone of NRH s network relative to UTC. The technology (see table at end of document) used by the NRH s network. The MCC of the subscriber s IMSI (International Mobile Subscriber Identity). The MNC of the subscriber s IMSI. The tyntec id of the subscription network s operator. The mapping can be found in the Customer Lounge under Home>Resource Center>Network Lists>Mobile Outbound SMS ( Human readable name of the subscription network s operator. The three-letter county code where the subscription network is located. Local time zone of the subscription network relative to UTC. The technology (see at end of document) used by the subscription network. The CC (Country Code) of the responding HLR (Home Location Register). The NDC (National Dailing Code) of the responding HLR. 9

10 hlrmcc hlrmnc hlrttid hlroperator hlrcountry hlrtimezone hlrtechnology msccc mscdnc mscmcc mscmnc mscttid msccountry msctimezone msctechnology ported roaming presence price currency integer country code following ISO alpha-3 +HH:mm (according to ISO 8601) according to ITU E.214 according to ITU E.214 integer country code following ISO alpha-3 +HH:mm (according to ISO 8601) float currency code following ISO 4217 A representative MCC of the HLR s operator. A representative MCN of the HLR s operator. The tyntec id of the HLR s operator. The mapping can be found in the Customer Lounge under Home>Resource Center>Network Lists>Mobile Outbound SMS ( Human readable name of the HLR s operator. The three-letter county code indicating where the HLR is located. Local time zone of the HLR relative to UTC. The technology (see following table) used by the HLR s network. The CC of the the MSC (Mobile Switching Center). The DNC of the MSC. A representative MCC of the MSC s operator. A representative MCN of the MSC s operator. The tyntec id of the MSC s operator. The mapping can be found in the Customer Lounge under Home>Resource Center>Network Lists>Mobile Outbound SMS ( The three-letter county code of the network operating the MSC. Local time zone of the MSC relative to UTC. The technology (see at end of document) used by the MSC s network. Indicating the porting status true/false/unknown. Indicating the roaming status true/false/unknown. Latest handset status (switched on/off) known by the operator (stored in respective HLR). The price for the query. The currency in which the pricing is given; corresponding to the currency of the invoice. 10

11 priceeffective errorcode date in the format yyyy-mm-ddth- H:mm:ss (according to ISO 8601) Possible values for errorcode can be found in the document GSM Error Codes. The date when the price became effective. 3.5 HTTP Status Codes HTTP Code Description 200 OK 400 Bad Request 401 Unauthorized 403 Forbidden 405 Method Not Allowed 415 Not Acceptable Network information will be suplied within the response. Any of the provided parameters is invalid or callbackurl is not reachable. HTTP basic authentification parameters are invalid. HTTP basic authentification parameters are missing. Request method is not support (this service only supports GET). Media type is not supported. 500 Internal Error 11

12 About tyntec tyntec ( is a telecom-web convergence company that connects the immediacy and convenience of telecom with the power of the Internet. Partnering with telecom operators around the world, tyntec enables enterprises and Internet brands to power their applications, authentication, and mission-critical communications with universal mobile services such as SMS, voice and phone numbers in the cloud. Founded in 2002, tyntec employs over 150 people in six offices around the globe, serving more than 500 global businesses, Internet brands and telecom operators. Munich Singapore London San Francisco sales@tyntec.com