Portability Check | Quick Start

Hi there!

So, you’ve got your tyntec API key from your Business Center and you are going to implement phone number checks in your app. Here’s a basic guide on how to do it with our REST API.

With tyntec’s Portability Check, you can easily check if a certain phone number is valid (working). Moreover, you can identify the operator and the country of the given phone number; and what type of network it uses so that you can decide if you should send an SMS to the number.

Endpoints

Endpoint URL	Purpose	Reference
https://api.tyntec.com/nis/v1/gnp	Portability checks	GNP

Step One: Set headers

Authorize your API calls by adding the HTTP header apikey with your tyntec API key.

Important: You use a trial API key for testing and a different API key when you go live!

The REST API accepts data in the JSON format (Content-Type: application/json) and responds with JSON data as well (Accept: application/json). You need to specify them only if your HTTP client has other defaults.

The complete headers look like this:

<div class="geshifilter"><pre class="php geshifilter-php">Content<span class="sy0">-</span>Type<span class="sy0">:</span> application<span class="sy0">/</span>json
Accept<span class="sy0">:</span> application<span class="sy0">/</span>json
apikey<span class="sy0">:</span> YOUR_API_KEY</pre></div>

Step Two: Make a portability check request

To check the given phone number, you need to send a GET request with the phone number in the parameter msisdn to the GNP endpoint.

The simplest request with the required parameter looks as follows:

<div class="geshifilter"><pre class="php geshifilter-php">GET https<span class="sy0">:</span><span class="co1">//api.tyntec.com/nis/v1/gnp?msisdn=PHONE_NUMBER </span></pre></div>

If you receive the 200 status, the request was successful. A correct request can also result in an error message when the phone number doesn’t exist.

Return of data can be both synchronous or asynchronous, and it is synchronous by default. The returned data contains requestId, errorCode, country, operator, and more (see the API Reference for details). Once you go live, the data also contains pricing information.

Request asynchronous return of data

If asynchronous return is more suitable for your app, specify a callbackUrl parameter in the query string to request it. The callbackUrl parameter is the URL that will receive the data from the GNP API.

Such request should look as follows:

<div class="geshifilter"><pre class="php geshifilter-php">GET https<span class="sy0">:</span><span class="co1">//api.tyntec.com/nis/v1/gnp?msisdn=PHONE_NUMBER&callbackUrl=https://your.server.com/endpoint</span></pre></div>

The immediate response to this request shows only the following info:

<div class="geshifilter"><pre class="php geshifilter-php"><span class="br0">{</span><span class="st_h">'requestId'</span><span class="sy0">:</span> <span class="st_h">'PHONE_NUMBER:133001:cda19914bdbd40e38c9a2716c12ee1a8'</span><span class="sy0">,</span> <span class="st_h">'synchronous'</span><span class="sy0">:</span> <span class="kw4">False</span><span class="br0">}</span></pre></div>

Note: The GNP API checks with a HEAD request first that your URL exists and only if your URL returns a successful response, the API POSTs the data.

Step Three: Interpret returned data

You can read a lot of useful information from the returned data.

If the phone number is not in the correct format, you get back a 400 response with the message: “Required parameter msisdn not numeric”.

Is the number valid (working)?

If the number is in the correct format but the number doesn’t exist, you will see the following data:

<div class="geshifilter"><pre class="php geshifilter-php"><span class="br0">{</span><span class="st_h">'requestId'</span><span class="sy0">:</span> <span class="st_h">'PHONE_NUMBER:133001:1bf877b9cc6248f1818668c9a4c4b122'</span><span class="sy0">,</span> <span class="st_h">'msisdn'</span><span class="sy0">:</span> <span class="st_h">'PHONE_NUMBER'</span><span class="sy0">,</span> <span class="st_h">'ported'</span><span class="sy0">:</span> <span class="st_h">'unknown'</span><span class="sy0">,</span> <span class="st_h">'errorCode'</span><span class="sy0">:</span> <span class="st_h">'ffff'</span><span class="sy0">,</span> <span class="st_h">'synchronous'</span><span class="sy0">:</span> <span class="kw4">True</span><span class="br0">}</span></pre></div>

Expected data for an existing number looks like this:

<div class="geshifilter"><pre class="php geshifilter-php"><span class="br0">{</span>
   <span class="st0">"requestId"</span><span class="sy0">:</span> <span class="st0">"XXXXX:133001:6ab3f2bd3dc0486e825592601b778ebc"</span><span class="sy0">,</span>
   <span class="st0">"msisdn"</span><span class="sy0">:</span> <span class="st0">"XXXX"</span><span class="sy0">,</span> <span class="co1">// The phone number of interest, given in international format</span>
   <span class="st0">"ported"</span><span class="sy0">:</span> <span class="st0">"false"</span><span class="sy0">,</span> <span class="co1">// An indication of the porting status (yes/no)</span>
   <span class="st0">"errorCode"</span><span class="sy0">:</span> <span class="st0">"0"</span><span class="sy0">,</span> <span class="co1">// The reason for an unsuccessful attempt</span>
   <span class="st0">"mcc"</span><span class="sy0">:</span> <span class="st0">"230"</span><span class="sy0">,</span> <span class="co1">// A representative MCC (Mobile Country Code) of the operator</span>
   <span class="st0">"mnc"</span><span class="sy0">:</span> <span class="st0">"01"</span><span class="sy0">,</span> <span class="co1">// A representative MNC (Mobile Network Code) of the operator</span>
   <span class="st0">"ttId"</span><span class="sy0">:</span> <span class="st0">"51"</span><span class="sy0">,</span> <span class="co1">// The respective tyntec ID of the network</span>
   <span class="st0">"operator"</span><span class="sy0">:</span> <span class="st0">"T-Mobile Czech Republic a.s."</span><span class="sy0">,</span>
   <span class="st0">"country"</span><span class="sy0">:</span> <span class="st0">"CZE"</span><span class="sy0">,</span>
   <span class="st0">"timeZone"</span><span class="sy0">:</span> <span class="st0">"+0200"</span><span class="sy0">,</span>
   <span class="st0">"technology"</span><span class="sy0">:</span> <span class="st0">"GSM"</span><span class="sy0">,</span> <span class="co1">// The technology used by the operator's network. Possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed</span>
   <span class="st0">"synchronous"</span><span class="sy0">:</span> <span class="kw4">true</span> <span class="co1">// Indicates whether the response body contains the number information(synchronous) or just the requestId of the asynchronous response</span>
<span class="br0">}</span></pre></div>

Where is the number registered?

If you want to find out in which country the servicing operator is located, you can read it from the response. Look at the value operator and if it doesn’t specify a locality (for example, “operator”: “T-Mobile Czech Republic a.s.”), you can use the value country, which holds a 3-letter ISO code of the country where the phone number is registered (in this case, “country”: “CZE”).

Does the number support SMS?

Number Information Services from tyntec can also help you to understand the network type of your customer’s phone number. Knowing the network types can help you save costs on SMS.

The network type is returned in the value technology. Unfortunately, you cannot scrap a number based purely on its network type, because there is no definitive list of all networks that don’t support SMS.

Let’s go through all the technologies you may encounter:

“Fixed” usually means a landline is used. Even though some landlines support SMS, it is not the norm and you should be cautious about it.

“Pager” can have fallback functionality (after an unsuccessful pager request) but in most cases, it is not a preferred technology.

“iDen” usually doesn’t support the SMS either.

The “Satellite” network type should work.

The types GSM, CDMA, MVNO (or their combinations) are most commonly used, and sending SMS to them is preferred. These should be safe to use.

Ooops… trouble?

If you encounter issues, first examine the response status. If the status is 400 (‘bad request’), there should be detailed information explaining what exactly went wrong. You may also submit a ticket regarding your issue. Our support team will appreciate it if you also add your requestId to your new ticket.

Verify

Quick Start