Portability Check

Version: v1.0

Specification Release Notes Other versions

tyntec's Portability Check (formerly know as Number information service - NIS)

Base URLs

https://api.tyntec.com/nis/v1/

Global Number Portability

Read GNP information

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/nis/v1/gnp?msisdn=49569858597 \
  -H 'Accept: application/json' \
  -H 'apiKey: API_KEY'

GET https://api.tyntec.com/nis/v1/gnp?msisdn=49569858597 HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json',
  'apiKey':'API_KEY'

};

fetch('https://api.tyntec.com/nis/v1/gnp?msisdn=49569858597',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apiKey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/nis/v1/gnp',
  params: {
  'msisdn' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apiKey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/nis/v1/gnp', params={
  'msisdn': '49569858597'
}, headers = headers)

print r.json()

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apiKey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/nis/v1/gnp', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/nis/v1/gnp?msisdn=49569858597");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apiKey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/nis/v1/gnp", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /gnp

Global Number Portability (GNP) request for the specified MSISDN

Parameters

Name	In	Type	Required	Description
msisdn	query	string	true	The phone number of interest, given in the international format
callbackUrl	query	string	false	The asynchronous response can be triggered by this request parameter. In this case, tyntec's application will POST the requested number information to your webserver at the given URL, instead of the default synchronous response given in the body of the "HTTP 200 OK" response. If your server does not answer "HTTP 200 OK" within two seconds, tyntec's application will retry to POST the number information after 1, 5, 10, 20, 30, 60 minutes for the maximum of 48 hours.

Detailed description

msisdn: The phone number of interest, given in the international format

callbackUrl: The asynchronous response can be triggered by this request parameter. In this case, tyntec's application will POST the requested number information to your webserver at the given URL, instead of the default synchronous response given in the body of the "HTTP 200 OK" response. If your server does not answer "HTTP 200 OK" within two seconds, tyntec's application will retry to POST the number information after 1, 5, 10, 20, 30, 60 minutes for the maximum of 48 hours.

Example responses

200 Response

{
  "requestId": "12-86cfafba-8677-f42b-5050-ece6af6abf01",
  "msisdn": "+491622943176",
  "ported": "false",
  "price": "0.001",
  "currency": "EUR",
  "priceEffective": "2010-11-01T00:00:00+0000",
  "errorCode": "0",
  "mcc": "262",
  "mnc": "02",
  "ttid": "15",
  "operator": "Vodafone",
  "country": "DEU",
  "timezone": "+0100",
  "technology": "GSM",
  "synchronous": "true"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful GNP response; in the case a valid callbackUrl is provided, the response will be the requestId.	GnpResponse
400	Bad Request	Error in MSISDN or in callback URL	Problem
401	Unauthorized	Invalid account credentials	Problem
402	Payment Required	The current credit balance is not sufficient for this request.	Problem
403	Forbidden	Authorization information is missing.	Problem
500	Internal Server Error	Something went wrong. :-(	Problem

Global Number Verification

Read GNV information

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/nis/v1/gnv?msisdn=49569858597 \
  -H 'Accept: application/json' \
  -H 'apiKey: API_KEY'

GET https://api.tyntec.com/nis/v1/gnv?msisdn=49569858597 HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json',
  'apiKey':'API_KEY'

};

fetch('https://api.tyntec.com/nis/v1/gnv?msisdn=49569858597',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apiKey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/nis/v1/gnv',
  params: {
  'msisdn' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apiKey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/nis/v1/gnv', params={
  'msisdn': '49569858597'
}, headers = headers)

print r.json()

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apiKey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/nis/v1/gnv', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/nis/v1/gnv?msisdn=49569858597");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apiKey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/nis/v1/gnv", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /gnv

Global Number Verification (GNV) request for the specified MSISDN

Parameters

Name	In	Type	Required	Description
msisdn	query	string	true	The phone number of interest, given in the international format
callbackUrl	query	string	false	The asynchronous response can be triggered by this request parameter. In this case, tyntec's application will POST the requested number information to your webserver at the given URL, instead of the default synchronous response given in the body of the "HTTP 200 OK" response. If your server does not answer "HTTP 200 OK" within two seconds, tyntec's application will retry to POST the number information after 1, 5, 10, 20, 30, 60 minutes for the maximum of 48 hours.

Detailed description

msisdn: The phone number of interest, given in the international format

Example responses

200 Response

{
  "requestId": "12-86cfafba-8677-f42b-5050-ece6af6abf01",
  "msisdn": "+491622943176",
  "ported": "false",
  "roaming": "false",
  "presence": "true",
  "price": 0.001,
  "currency": "EUR",
  "priceEffective": "2010-11-01T00:00:00+0000",
  "errorCode": "0",
  "nrhMCC": "262",
  "nrhMNC": "02",
  "nrhTtId": "15",
  "nrhOperator": "Vodafone",
  "nrhCountry": "DEU",
  "nrhTimeZone": "+0100",
  "nrhTechnology": "GSM",
  "imsiMCC": "262",
  "imsiMNC": "02",
  "imsi": "string",
  "imsiTtId": "15",
  "imsiOperator": "Vodafone",
  "imsiCountry": "DEU",
  "imsiTimeZone": "+0100",
  "imsiTechnology": "GSM",
  "hlrCC": "49",
  "hlrNDC": "162",
  "hlrMCC": "262",
  "hlrMNC": "02",
  "hlr": "string",
  "hlrTtId": "15",
  "hlrOperator": "Vodafone",
  "hlrCountry": "DEU",
  "hlrTimeZone": "+0100",
  "hlrTechnology": "GSM",
  "mscCC": "49",
  "mscNDC": "162",
  "mscMCC": "262",
  "mscMNC": "02",
  "msc": "string",
  "mscTtId": "15",
  "mscOperator": "Vodafone",
  "mscCountry": "DEU",
  "mscTimeZone": "+0100",
  "mscTechnology": "GSM",
  "synchronous": "true"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful GNV response	GnvResponse
400	Bad Request	Error in MSISDN or in callback URL	Problem
401	Unauthorized	Invalid account credentials	Problem
402	Payment Required	The current credit balance is not sufficient for this request.	Problem
403	Forbidden	Authorization information is missing.	Problem
500	Internal Server Error	Something went wrong. :-(	Problem

Schemas

GnpResponse

{
  "requestId": "12-86cfafba-8677-f42b-5050-ece6af6abf01",
  "msisdn": "+491622943176",
  "ported": "false",
  "price": "0.001",
  "currency": "EUR",
  "priceEffective": "2010-11-01T00:00:00+0000",
  "errorCode": "0",
  "mcc": "262",
  "mnc": "02",
  "ttid": "15",
  "operator": "Vodafone",
  "country": "DEU",
  "timezone": "+0100",
  "technology": "GSM",
  "synchronous": "true"
}

The number information response for GNP

Properties

Name	Type	Required	Restrictions	Description
requestId	string	false	none	The unique identifier provided for each request
msisdn	string	false	none	The phone number of interest given in the international format
ported	string	false	none	Indication of the porting status (yes/no)
price	number	false	none	The price for the query
currency	string	false	none	The currency in which the pricing is given; it corresponds to the currency of the invoice.
priceEffective	string	false	none	The date when "price" became effective
errorCode	string	false	none	The reason for an unsuccessful attempt
mcc	string	false	none	Representative MCC (Mobile Country Code) of the operator
mnc	string	false	none	Representative MNC (Mobile Network Code) of the operator
ttid	string	false	none	Respective tyntec ID of the network
operator	string	false	none	Human-readable name of the operator
country	string	false	none	The three-letter code (following ISO 3166-1 alpha-3) of the country where the operator is located
timezone	string	false	none	The operator's local time zone relative to UTC
technology	string	false	none	Technology used by the operator's network; possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed.
synchronous	boolean	false	none	Indicates whether the response body contains the number information (synchronous) or just the requestId of the asynchronous response.

GnvResponse

{
  "requestId": "12-86cfafba-8677-f42b-5050-ece6af6abf01",
  "msisdn": "+491622943176",
  "ported": "false",
  "roaming": "false",
  "presence": "true",
  "price": 0.001,
  "currency": "EUR",
  "priceEffective": "2010-11-01T00:00:00+0000",
  "errorCode": "0",
  "nrhMCC": "262",
  "nrhMNC": "02",
  "nrhTtId": "15",
  "nrhOperator": "Vodafone",
  "nrhCountry": "DEU",
  "nrhTimeZone": "+0100",
  "nrhTechnology": "GSM",
  "imsiMCC": "262",
  "imsiMNC": "02",
  "imsi": "string",
  "imsiTtId": "15",
  "imsiOperator": "Vodafone",
  "imsiCountry": "DEU",
  "imsiTimeZone": "+0100",
  "imsiTechnology": "GSM",
  "hlrCC": "49",
  "hlrNDC": "162",
  "hlrMCC": "262",
  "hlrMNC": "02",
  "hlr": "string",
  "hlrTtId": "15",
  "hlrOperator": "Vodafone",
  "hlrCountry": "DEU",
  "hlrTimeZone": "+0100",
  "hlrTechnology": "GSM",
  "mscCC": "49",
  "mscNDC": "162",
  "mscMCC": "262",
  "mscMNC": "02",
  "msc": "string",
  "mscTtId": "15",
  "mscOperator": "Vodafone",
  "mscCountry": "DEU",
  "mscTimeZone": "+0100",
  "mscTechnology": "GSM",
  "synchronous": "true"
}

The number information response for GNV

Properties

Name	Type	Required	Restrictions	Description
requestId	string	false	none	The unique identifier provided for each request
msisdn	string	false	none	The phone number of interest given in the international format
ported	string	false	none	Indicates the porting status true/false/unknown.
roaming	string	false	none	Indicates the roaming status true/false/unknown.
presence	string	false	none	The latest handset status (switched on/off) known by the operator (stored in the respective HLR)
price	number	false	none	The price for the query
currency	string	false	none	The currency in which the pricing is given; it corresponds to the currency of the invoice.
priceEffective	string	false	none	The date when "price" became effective
errorCode	string	false	none	The reason for an unsuccessful attempt
nrhMCC	string	false	none	Representative MCC (Mobile Country Code) of the NRH's network (Number Range Holder)
nrhMNC	string	false	none	Representative MNCs (Mobile Network Codes) of the NRH's network
nrhTtId	string	false	none	Respective tyntec ID of the NRH
nrhOperator	string	false	none	Human-readable name of the NRH
nrhCountry	string	false	none	The three-letter code (following ISO 3166-1 alpha-3) of the country where the NRH's network is located
nrhTimeZone	string	false	none	Local time zone of the NRH's network, relative to UTC
nrhTechnology	string	false	none	The technology used by the NRH operator's network; possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed.
imsiMCC	string	false	none	MCC of the subscriber's IMSI (International Mobile Subscriber Identity)
imsiMNC	string	false	none	MNC of the subscriber's IMSI
imsi	string	false	none	The subscriber's International Mobile Subscriber Identity
imsiTtId	string	false	none	Respective tyntec ID of the subscription network operator
imsiOperator	string	false	none	Human-readable name of the subscription network operator
imsiCountry	string	false	none	The three-letter code of the country where the subscription network is located
imsiTimeZone	string	false	none	Local time zone of the subscription network, relative to UTC
imsiTechnology	string	false	none	The technology used by the subscription network; possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed.
hlrCC	string	false	none	The CC (Country Code) of the responding HLR (Home Location Register)
hlrNDC	string	false	none	The NDC (National Dialling Code) of the responding HLR
hlrMCC	string	false	none	Representative MCC of the HLR's operator
hlrMNC	string	false	none	Representative MNC of the HLR's operator
hlr	string	false	none	Representative Home Location Register
hlrTtId	string	false	none	Respective tyntec ID of the operator's HLR
hlrOperator	string	false	none	Human-readable name of operator's HLR
hlrCountry	string	false	none	The three-letter code of the country where the HLR is located
hlrTimeZone	string	false	none	Local time zone of the HLR, relative to UTC; +HH:mm (according to ISO 8601)
hlrTechnology	string	false	none	The technology used by the HLR operator network; possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed.
mscCC	string	false	none	The CC of the MSC (Mobile Switching Center)
mscNDC	string	false	none	The MSC of the NDC
mscMCC	string	false	none	Representative MCC of the operator's MSC
mscMNC	string	false	none	Representative MNC of the operator's MSC
msc	string	false	none	Representative Mobile Switching Center
mscTtId	string	false	none	Respective tyntec ID of the operator's MSC
mscOperator	string	false	none	Human-readable name of operator's MSC
mscCountry	string	false	none	The three-letter country code (following ISO 3166-1 alpha-3) of the network operating the MSC
mscTimeZone	string	false	none	Local time zone of the MSC, relative to UTC; +HH:mm (according to ISO 8601)
mscTechnology	string	false	none	The technology used by the MSC operator's network; possible values are: GSM, MVNO GSM, GSM/CDMA, Satellite, CDMA, iDen, iDen/GSM, Pager, Fixed.
synchronous	boolean	false	none	Indicates whether the response body contains the number information (synchronous) or just the requestId of the asynchronous response

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "The given data were not parsable.",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

The problem object follows the RFC-7807 (https://tools.ietf.org/html/rfc7807).

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	A URI reference [RFC3986] that identifies the problem type
title	string	true	none	Short, human-readable summary of the problem type
status	string	true	none	The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem
detail	string	true	none	Human-readable explanation specific to this occurrence of the problem