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 |
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:
Content-Type: application/json
Accept: application/json
apikey: YOUR_API_KEY
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:
GET https://api.tyntec.com/nis/v1/gnp?msisdn=PHONE_NUMBER
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:
GET https://api.tyntec.com/nis/v1/gnp?msisdn=PHONE_NUMBER&callbackUrl=https://your.server.com/endpoint
The immediate response to this request shows only the following info:
{'requestId': 'PHONE_NUMBER:133001:cda19914bdbd40e38c9a2716c12ee1a8', 'synchronous': False}
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:
{'requestId': 'PHONE_NUMBER:133001:1bf877b9cc6248f1818668c9a4c4b122', 'msisdn': 'PHONE_NUMBER', 'ported': 'unknown', 'errorCode': 'ffff', 'synchronous': True}
Expected data for an existing number looks like this:
{
"requestId": "XXXXX:133001:6ab3f2bd3dc0486e825592601b778ebc",
"msisdn": "XXXX", // The phone number of interest, given in international format
"ported": "false", // An indication of the porting status (yes/no)
"errorCode": "0", // The reason for an unsuccessful attempt
"mcc": "230", // A representative MCC (Mobile Country Code) of the operator
"mnc": "01", // A representative MNC (Mobile Network Code) of the operator
"ttId": "51", // The respective tyntec ID of the network
"operator": "T-Mobile Czech Republic a.s.",
"country": "CZE",
"timeZone": "+0200",
"technology": "GSM", // The technology used by the operator's network. Possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed
"synchronous": true // Indicates whether the response body contains the number information(synchronous) or just the requestId of the asynchronous response
}
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.