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:
Content-Type: application/json Accept: application/json apikey: YOUR_API_KEY
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.
GET https://api.tyntec.com/nis/v1/gnp?msisdn=PHONE_NUMBER&callbackUrl=https://your.server.com/endpoint
{'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.
{'requestId': 'PHONE_NUMBER:133001:1bf877b9cc6248f1818668c9a4c4b122', 'msisdn': 'PHONE_NUMBER', 'ported': 'unknown', 'errorCode': 'ffff', 'synchronous': True}
{ "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.