Shell HTTP JavaScript Ruby Python Java Go PHP
Code copied successfuly

Phone Verification API

Version: v1.0

Specification Release Notes Other versions

Base URLs

Phone Verification

Phone Verification service aims to determine validity, reachability and fraud risk of phone numbers entered into forms by users or auto dialers so that brands can ensure their customer records are accurate, improve conversion rates for customer outreach, and guard against bad actors.

The API determines the reachability and trustworthiness of phone numbers through:

  • Validity Check: check if the phone number is valid according to the numbering plan for that country.
  • Active Status: check if the phone number has been assigned to a subscriber by an operator.
  • Number Type: determine the phone number type to decide which technology to use to communicate.
  • Mobile Operator: identify the name and the country of the home network operator for the subscriber.
  • Outreach Status: check if an SMS can be delivered to the subscriber behind the phone number.
  • Fraud Risk: determine the likelihood of the phone number being used by a bad actor.

Verify Number

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/verification/v1/phone/{number} \
  -H 'Accept: application/json' \
  -H 'apiKey: API_KEY'


GET https://api.tyntec.com/verification/v1/phone/{number} HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apiKey: API_KEY



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

};

fetch('https://api.tyntec.com/verification/v1/phone/{number}',
{
  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/verification/v1/phone/{number}',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.get('https://api.tyntec.com/verification/v1/phone/{number}', params={

}, 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/verification/v1/phone/{number}', 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/verification/v1/phone/{number}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apiKey", "API_KEY");

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/verification/v1/phone/{number}", data)
    req.Header = headers

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

GET /phone/{number}

Phone Verification is a web service that responds with information regarding the validity, reachability and trustworthiness of a phone number.

Parameters

Name In Type Required Description
number path string true The phone number to be verified, given in the international format
Detailed description

number: The phone number to be verified, given in the international format

Example responses

200 Response

{
  "validNumberFormat": "true",
  "activeNumber": "true",
  "numberType": "mobile",
  "operatorName": "T-Mobile Czech Republic a.s.",
  "operatorCountry": "CZE",
  "fraudRisk": "low",
  "outreachReady": "true"
}

Responses

Status Meaning Description Schema
200 OK A valid request numberResponse
401 Unauthorized Missing or Invalid API credentials errorResponse401
403 Forbidden Permission denied errorResponse403

Metadata

Metadata information regarding the API itself. The information exposed is:

  • API Health: Information regarding the status of the API.
  • Version: The version of the API and API specification.

Phone Verification API health

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/verification/v1/health \
  -H 'Accept: application/json' \
  -H 'apiKey: API_KEY'


GET https://api.tyntec.com/verification/v1/health HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apiKey: API_KEY



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

};

fetch('https://api.tyntec.com/verification/v1/health',
{
  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/verification/v1/health',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.get('https://api.tyntec.com/verification/v1/health', params={

}, 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/verification/v1/health', 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/verification/v1/health");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apiKey", "API_KEY");

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/verification/v1/health", data)
    req.Header = headers

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

GET /health

Phone Verification health endpoint provides information about the status of the API

Example responses

200 Response

{
  "status": "up",
  "updatedAt": 12321546464
}

Responses

Status Meaning Description Schema
200 OK API is up and running healthResponse
403 Forbidden Permission denied errorResponse403

Phone Verification API version

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/verification/v1/version \
  -H 'Accept: application/json' \
  -H 'apiKey: API_KEY'


GET https://api.tyntec.com/verification/v1/version HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apiKey: API_KEY



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

};

fetch('https://api.tyntec.com/verification/v1/version',
{
  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/verification/v1/version',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.get('https://api.tyntec.com/verification/v1/version', params={

}, 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/verification/v1/version', 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/verification/v1/version");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apiKey", "API_KEY");

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/verification/v1/version", data)
    req.Header = headers

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

GET /version

Phone Verification version endpoint provides information about the current version of the Phone Verification API

Example responses

200 Response

{
  "version": "v0",
  "updatedAt": 12321546464
}

Responses

Status Meaning Description Schema
200 OK The current API version versionResponse
403 Forbidden Permission denied errorResponse403

Schemas

numberResponse

{
  "validNumberFormat": "true",
  "activeNumber": "true",
  "numberType": "mobile",
  "operatorName": "T-Mobile Czech Republic a.s.",
  "operatorCountry": "CZE",
  "fraudRisk": "low",
  "outreachReady": "true"
}

Properties

Name Type Required Restrictions Description
validNumberFormat string false none Is the number formatted correctly according to the numbering plan? Possible values (true, false)
activeNumber string false none Is the number currently assigned to a subscriber? Possible values (true, false, unknown)
numberType string false none Type of the phone number. Possible values (fixed, mobile, fixed_or_mobile, mvno gsm, iden, cdma, gsm cdma, toll_free, premium_rate, shared_cost, voip, personal, pager, uan, voicemail, unknown)
operatorName string false none Who is the home network operator of the subscriber?
operatorCountry string false none In which country is the number registered? The country if formated in ISO3 code
fraudRisk string false none What is the likelihood of the number being associated with fraud? Possible values (low, medium, high, unknown)
outreachReady string false none Should a message be sent to this number? Possible values (true, false)

healthResponse

{
  "status": "up",
  "updatedAt": 12321546464
}

Properties

Name Type Required Restrictions Description
status string false none none
updatedAt integer false none Timestamp

versionResponse

{
  "version": "v0",
  "updatedAt": 12321546464
}

Properties

Name Type Required Restrictions Description
version string false none none
updatedAt integer false none Timestamp

errorResponse401

{
  "error": "No API key found in request"
}

Properties

Name Type Required Restrictions Description
error string false none An error message of an unsuccessful request

errorResponse403

{
  "error": "Invalid authentication credentials"
}

Properties

Name Type Required Restrictions Description
error string false none An error message of an unsuccessful request

Number Portability API

Version: v1.0

Specification Release Notes Other versions

tyntec's Number Portability is a service that resolves whether a phone number is ported to a different operator than the one originally issued this phone number. Information is obtained through data provided directly from local number portability databases and live network information from across the globe.

Base URLs

Number Portability

tyntec's Global Number Portability (GNP) resolves number portability by obtaining data directly from local number portability databases and live network information from across the globe.

Number Portability check

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
apiKey: API_KEY



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");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apiKey", "API_KEY");

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

Many mobile subscribers are moving their phone numbers to different mobile operators. This is called Portability in the telecom terminology. Number Portability check provides information on whether a phone number is ported to a different mobile operator and who is the new operator.

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.
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 system 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 system will retry to POST the number information after 1, 5, 10, 20, 30, 60 minutes for a 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 A successful GNP response; in the case a valid callbackUrl is provided, the response will be the requestId. GnpResponse
400 Bad Request An error in MSISDN or in the 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 An indication of the porting status
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 A representative MCC (Mobile Country Code) of the operator
mnc string false none A representative MNC (Mobile Network Code) of the operator
ttid string false none The respective tyntec ID of the network
operator string false none A 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 The 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.

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

HLR Lookup API

Version: v1.0

Specification Release Notes Other versions

HLR lookup is a service that minimizes message loss and unsuccessful call attempts with real-time phone number verification, providing key information on a user's phone number, such as subscriber status and roaming data.

Base URLs

HLR Lookup

tyntec's Global Number Verification (GNV) minimizes message loss and unsuccessful call attempts with real-time phone number verification, providing key information on a user's phone number, such as subscriber status and roaming data.

Number Information from HLR

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
apiKey: API_KEY



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");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apiKey", "API_KEY");

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

Extended Number Information can be requested directly from the Home Location Registry (HLR) serving the specific 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.
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 system 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 system will retry to POST the number information after 1, 5, 10, 20, 30, 60 minutes for a maximum of 48 hours.

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 A successful GNV response GnvResponse
400 Bad Request An error in MSISDN or in the 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

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 A representative MCC (Mobile Country Code) of the NRH's network (Number Range Holder)
nrhMNC string false none A representative MNCs (Mobile Network Codes) of the NRH's network
nrhTtId string false none The respective tyntec ID of the NRH
nrhOperator string false none A 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 The MCC of the subscriber's IMSI (International Mobile Subscriber Identity)
imsiMNC string false none The MNC of the subscriber's IMSI
imsi string false none The subscriber's International Mobile Subscriber Identity
imsiTtId string false none The respective tyntec ID of the subscription network operator
imsiOperator string false none A 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 The 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 A representative MCC of the HLR's operator
hlrMNC string false none A representative MNC of the HLR's operator
hlr string false none The representative Home Location Register
hlrTtId string false none The respective tyntec ID of the operator's HLR
hlrOperator string false none A human-readable name of the operator's HLR
hlrCountry string false none The three-letter code of the country where the HLR is located
hlrTimeZone string false none The 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 A representative MCC of the operator's MSC
mscMNC string false none A representative MNC of the operator's MSC
msc string false none The representative Mobile Switching Center
mscTtId string false none The respective tyntec ID of the operator's MSC
mscOperator string false none A human-readable name of the 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 The 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 false none A URI reference [RFC3986] that identifies the problem type
title string false none Short, human-readable summary of the problem type
status number false none The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem
detail string false none Human-readable explanation specific to this occurrence of the problem
Terms and Conditions Support and Service Level Agreements Acceptable Use Policy Data Privacy Statement Disclaimer GDPR Compliance Imprint
© 2021 tyntec. All rights reserved
Shell HTTP JavaScript Ruby Python Java Go PHP