Thumbnail
Portability Check | Connection Steps

Follow the steps below to learn more about the Connection Steps for our Portability Check product.

If any questions arise while reading, you can contact us under support@tyntec.com

Connection Steps

1. Query information on phone number

The number information on a specific Mobile Station International Subscriber Directory Number (MSISDN) can be queried from two resources:

Resource URL Method
${baseURL}/gnp GET

 

The MSISDN is provided in the respective parameter:

1 | ?msisdn=$msisdn

In this case, tyntec‘s application will return the requested number information on the given MSISDN ($msisdn).

To prevent incurring avoidable costs due to malformed requests, tyntec‘s application server performs a consistency check on the provided MSISDN and callbackUrl before processing the request.

 

 

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 Global Number Portability service 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:

1 | ?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 two seconds.

 

3. Code Examples

The following code blocks give examples of how to query number information on an MSISDN.

Example for Query GNP (synchronous response):

1 | curl
2 |     -u username:password
3 |     -X GET
4 |     -H "Accept: application/json"
5 |     https://rest.tyntec.com/nis/v1/gnp?msisdn=+491622943176

Example for Query GNP (asynchronous response):

1 | curl
2 |     -u username:password
3 |     -X GET
4 |     -H "Accept: application/json"
5 |     https://rest.tyntec.com/nis/v1/gnp?msisdn=+491622943176&callbackUrl=https://rest.customer.com/inbound/

 Response to Query GNP containing the requested number information:

 1 | {
 2 | "requestId":"12-86cfafba-8677-f42b-5050-ece6af6abf01",
 3 | "msisdn":"+491622943176",
 4 |  "mcc":"262",
 5 |  "mnc":"02",
 6 |  "ttId":15,
 7 | "operator":" Vodafone",
 8 |  "country":"DEU",
 9 |  "timeZone":"+0100",
10 |  "technology":"GSM",
11 |  "ported":"false",
12 |  "price":0.001,
13 |  "currency":"EUR",
14 |  "priceEffective":"2010-11-01T00:00:00+0000",
15 |  "errorCode":"0"
16 | }

 

In this request, there are a number of parameters that need to be defined, while others are optional:

 

Parameter Possible Values Description
requestID UUID according to RFC 4122 The unique identifier provided for each request.
msisdn Phone number according to ITU E.164 The phone number of interest given in international format.
MCC UTF-8 encoded string according to ITU E.212 A representative MCC (Mobile Country Code) of the operator.
MNC UTF-8 encoded strong according to ITU E.212 A representative MNC (Mobile Network Code) of the operator.
ttId integer The respective tyntec ID of the network.
operator string The human readable name of the operator.
country Country code following ISO 3166-1 alpha-3 The three-letter country code where the operator is located.
timeZone +HH:mm (according to ISO 8601) The operator’s local time zone relative to UTC.
technology UTF-8 encoded string Technology used by the operator’s network. Possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed.
ported boolean An indication of the porting status (yes/no).
price float The price for the query.
currency Currency code following ISO 4217 The currency in which the pricing is given; corresponding to the currency of the invoice.
priceEffective Date in the format “yyyy-MM-ddTHH:mm:ss” (according to ISO 8601) The date when “price” became effective.
errorCode The reason for an unsuccessful attempts. Possible values for error codes are given in a following table.

4. HTTP Status Codes

HTTP Code Description
200 OK Network information will be supplied within the response.
400 Bad Request Any of the provided parameters is invalid or callbackUrl is not reachable.
401 Unauthorized HTTP basic authentication parameters are invalid.
403 Forbidden HTTP basic authentication parameters are missing.
405 Method Not Allowed Request method is not support (this service only supports GET).
415 Not Acceptable Media type is not supported.
500 Internal Error