Shell HTTP JavaScript Ruby Python Java Go PHP
Code copied successfuly

Verify API

Version: v1.0.0

Specification Release Notes Other versions

This is openAPI file Verify product

Base URLs

Verify with Criteria Templates

Verify service aims to provide information regarding phone numbers.

Customers can define their own logic for verifying a number, by defining verify criteria templates. Customers can also define the response parameters that they would like to receive back.

This dynamic configuration, provides customers with full control over tyntec's verify service.

Create criteria template

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/verify/v1/templates \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apiKey: API_KEY'


POST https://api.tyntec.com/verify/v1/templates HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apiKey: API_KEY


const inputBody = '{
  "name": "verify-criteria",
  "description": "provide criteria description",
  "criteria": [
    {
      "activeNumber": {
        "is": true
      }
    }
  ],
  "response": [
    "validNumberFormat",
    "numberType",
    "activeNumber",
    "operatorName",
    "operatorCountry",
    "mcc",
    "mnc",
    "disposableNumber"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apiKey':'API_KEY'

};

fetch('https://api.tyntec.com/verify/v1/templates',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


require 'rest-client'
require 'json'

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

result = RestClient.post 'https://api.tyntec.com/verify/v1/templates',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.post('https://api.tyntec.com/verify/v1/templates', params={

}, headers = headers)

print(r.json())


<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('POST','https://api.tyntec.com/verify/v1/templates', 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/verify/v1/templates");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
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{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "apiKey": []string{"API_KEY"},

    }

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

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

POST /templates

Create a Verify criteria template with desired verify rules and responses. Verify template creation is a crucial step in the Verify process. Without this step Verify process cannot be done.

There are two types of Verify criteria templates:

  • Empty template or,
  • Customized template

Empty Verify criteria template

Empty template means that the default verify and response parameters will be used. This practically means:

  • Verify criteria

    • validNumberFormat: Verify that the phone number has a valid format
    • numberType: Verify that the phone number type is fixed or mobile

  • Response parameters

    • requestId: Unique request identifier
    • verified: Verify outcome
    • reason (only in case of unverified response)
    • reasonCode (only in case of unverified response)

Customized Verify criteria template

Customized templates are more complex to define but more powerful, since customers can define exactly how the Verify service should verify phone numbers and how the response should look like.

The following verify parameter can be configured:

Criterion Allowed Operations Allowed Values
activeNumber is true/false
numberType is, is_in fixed or mobile.

In case of is_in operator multiple comma separated values can be provided
operatorCountry is, is_in country in ISO Alpha-3 format e.g. DEU, GBR.

In case of is_in operator multiple comma separated values can be provided
disposableNumber is true/false
mccMnc is, is_in MCC and MNC of the operator e.g. 23202.

In case of is_in operator multiple comma separated values can be provided

The following parameters can be configured for the response:

  • validNumberFormat
  • numberType
  • activeNumber
  • operatorName
  • OperatorCountry
  • mcc
  • mnc
  • disposableNumber

In the Response message, parameters will respect the template configuration order.

Moreover, following parameters will be always shown in the response

  • requestId
  • verified
  • reason (only in case of unverified response)
  • reasonCode (only in case of unverified response)

However, customers can use those parameters in the response configuration just for manipulating the order of the Response parameters.

Body parameter

{
  "name": "verify-criteria",
  "description": "provide criteria description",
  "criteria": [
    {
      "activeNumber": {
        "is": true
      }
    }
  ],
  "response": [
    "validNumberFormat",
    "numberType",
    "activeNumber",
    "operatorName",
    "operatorCountry",
    "mcc",
    "mnc",
    "disposableNumber"
  ]
}

Parameters

Name In Type Required Description
body body CreateCriteria true none

Example responses

200 Response

{
  "template": "verify-criteria",
  "message": "Created"
}

Responses

Status Meaning Description Schema
200 OK Valid request ReturnCreatedCriteria
400 Bad Request Bad request / Invalid request parameters error400
401 Unauthorized Missing or Invalid API credentials error401
403 Forbidden Permission denied error403
404 Not Found Not Found error404
409 Conflict Conflict error409
500 Internal Server Error Internal server error error500

View all criteria templates

Code samples

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


GET https://api.tyntec.com/verify/v1/templates 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/verify/v1/templates',
{
  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/verify/v1/templates',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.get('https://api.tyntec.com/verify/v1/templates', 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/verify/v1/templates', 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/verify/v1/templates");
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/verify/v1/templates", data)
    req.Header = headers

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

GET /templates

Retrieve all verify criteria templates created by the customer.

Example responses

200 Response

{
  "id": "4457068c-194d-4f72-9550-13b81ec054a9",
  "name": "verify-criteria",
  "description": "provide criteria description",
  "criteria": [
    {
      "activeNumber": {
        "is": true
      }
    }
  ],
  "response": [
    "validNumberFormat",
    "numberType",
    "activeNumber",
    "operatorName",
    "operatorCountry",
    "mcc",
    "mnc",
    "disposableNumber"
  ]
}

Responses

Status Meaning Description Schema
200 OK Valid request RetrieveAllCriteria
400 Bad Request Bad request / Invalid request parameters error400
401 Unauthorized Missing or Invalid API credentials error401
403 Forbidden Permission denied error403
404 Not Found Not Found error404
500 Internal Server Error Internal server error error500

View a criteria template

Code samples

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


GET https://api.tyntec.com/verify/v1/templates/{name} 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/verify/v1/templates/{name}',
{
  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/verify/v1/templates/{name}',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.get('https://api.tyntec.com/verify/v1/templates/{name}', 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/verify/v1/templates/{name}', 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/verify/v1/templates/{name}");
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/verify/v1/templates/{name}", data)
    req.Header = headers

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

GET /templates/{name}

Customers can view a specific criteria by knowing the criteria name.

Parameters

Name In Type Required Description
criteriaTemplateName path string true Criteria template name

Example responses

200 Response

{
  "id": "4457068c-194d-4f72-9550-13b81ec054a9",
  "name": "verify-criteria",
  "description": "provide criteria description",
  "criteria": [
    {
      "activeNumber": {
        "is": true
      }
    }
  ],
  "response": [
    "validNumberFormat",
    "numberType",
    "activeNumber",
    "operatorName",
    "operatorCountry",
    "mcc",
    "mnc",
    "disposableNumber"
  ]
}

Responses

Status Meaning Description Schema
200 OK Valid request RetrieveAllCriteria
400 Bad Request Bad request / Invalid request parameters error400
401 Unauthorized Missing or Invalid API credentials error401
403 Forbidden Permission denied error403
404 Not Found Not Found error404
500 Internal Server Error Internal server error error500

Update criteria template

Code samples

# You can also use wget
curl -X PUT https://api.tyntec.com/verify/v1/templates/{name} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apiKey: API_KEY'


PUT https://api.tyntec.com/verify/v1/templates/{name} HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apiKey: API_KEY


const inputBody = '{
  "name": "verify-criteria",
  "description": "modified criteria description",
  "criteria": [
    {
      "activeNumber": {
        "is": true
      }
    }
  ],
  "response": [
    "operatorName",
    "operatorCountry",
    "mcc",
    "mnc"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apiKey':'API_KEY'

};

fetch('https://api.tyntec.com/verify/v1/templates/{name}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});


require 'rest-client'
require 'json'

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

result = RestClient.put 'https://api.tyntec.com/verify/v1/templates/{name}',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.put('https://api.tyntec.com/verify/v1/templates/{name}', params={

}, headers = headers)

print(r.json())


<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('PUT','https://api.tyntec.com/verify/v1/templates/{name}', 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/verify/v1/templates/{name}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
con.setRequestProperty("Content-Type", "application/json");
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{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "apiKey": []string{"API_KEY"},

    }

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

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

PUT /templates/{name}

Modify an existing criteria template. Customers can update name, description, criteria and response by providing the whole json structure.

Criteria can be modified similarly with the criteria template creation.

There are two types of Verify criteria templates:

  • Empty template or,
  • Customized template

Empty Verify criteria template

Empty template means that the default verify and response parameters will be used. This practically means:

  • Verify criteria

    • validNumberFormat: Verify that the phone number has a valid format
    • numberType: Verify that the phone number type is fixed or mobile

  • Response parameters

    • requestId: Unique request identifier
    • verified: Verify outcome
    • reason (only in case of unverified response)
    • reasonCode (only in case of unverified response)

Customized Verify criteria template

Customized templates are more complex to define but more powerful, since customers can define exactly how the Verify service should verify phone numbers and how the response should look like.

The following verify parameter can be configured:

Criterion Allowed Operations Allowed Values
activeNumber is true/false
numberType is, is_in fixed or mobile.

In case of is_in operator multiple comma separated values can be provided
operatorCountry is, is_in country in ISO Alpha-3 format e.g. DEU, GBR.

In case of is_in operator multiple comma separated values can be provided
disposableNumber is true/false
mccMnc is, is_in MCC and MNC of the operator e.g. 23202.

In case of is_in operator multiple comma separated values can be provided

The following parameters can be configured for the response:

  • validNumberFormat
  • numberType
  • activeNumber
  • operatorName
  • OperatorCountry
  • mcc
  • mnc
  • disposableNumber

In the Response message, parameters will respect the template configuration order.

Moreover, following parameters will be always shown in the response

  • requestId
  • verified
  • reason (only in case of unverified response)
  • reasonCode (only in case of unverified response)

However, customers can use those parameters in the response configuration just for manipulating the order of the Response parameters.

Body parameter

{
  "name": "verify-criteria",
  "description": "modified criteria description",
  "criteria": [
    {
      "activeNumber": {
        "is": true
      }
    }
  ],
  "response": [
    "operatorName",
    "operatorCountry",
    "mcc",
    "mnc"
  ]
}

Parameters

Name In Type Required Description
criteriaTemplateName path string true Criteria template name
body body UpdateCriteria true none

Example responses

200 Response

{
  "template": "verify-criteria",
  "message": "Updated"
}

Responses

Status Meaning Description Schema
200 OK Valid request ReturnUpdatedCriteria
400 Bad Request Bad request / Invalid request parameters error400
401 Unauthorized Missing or Invalid API credentials error401
403 Forbidden Permission denied error403
404 Not Found Not Found error404
409 Conflict Conflict error409
500 Internal Server Error Internal server error error500

Delete criteria template

Code samples

# You can also use wget
curl -X DELETE https://api.tyntec.com/verify/v1/templates/{name} \
  -H 'Accept: application/json' \
  -H 'apiKey: API_KEY'


DELETE https://api.tyntec.com/verify/v1/templates/{name} 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/verify/v1/templates/{name}',
{
  method: 'DELETE',

  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.delete 'https://api.tyntec.com/verify/v1/templates/{name}',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.delete('https://api.tyntec.com/verify/v1/templates/{name}', 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('DELETE','https://api.tyntec.com/verify/v1/templates/{name}', 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/verify/v1/templates/{name}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
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("DELETE", "https://api.tyntec.com/verify/v1/templates/{name}", data)
    req.Header = headers

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

DELETE /templates/{name}

Delete criteria template by using the criteria name.

Parameters

Name In Type Required Description
criteriaTemplateName path string true Criteria template name

Example responses

200 Response

{
  "template": "verify-criteria",
  "message": "Deleted"
}

Responses

Status Meaning Description Schema
200 OK Valid request DeleteCriteria
400 Bad Request Bad request / Invalid request parameters error400
401 Unauthorized Missing or Invalid API credentials error401
403 Forbidden Permission denied error403
404 Not Found Not Found error404
500 Internal Server Error Internal server error error500

Verify by criteria template

Code samples

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


GET https://api.tyntec.com/verify/v1/phone/{number}?criteria={criteriaTemplateName} 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/verify/v1/phone/{number}?criteria={criteriaTemplateName}',
{
  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/verify/v1/phone/{number}?criteria={criteriaTemplateName}',
  params: {
  }, headers: headers

p JSON.parse(result)


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

r = requests.get('https://api.tyntec.com/verify/v1/phone/{number}?criteria={criteriaTemplateName}', 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/verify/v1/phone/{number}?criteria={criteriaTemplateName}', 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/verify/v1/phone/{number}?criteria={criteriaTemplateName}");
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/verify/v1/phone/{number}?criteria={criteriaTemplateName}", data)
    req.Header = headers

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

GET /phone/{number}?criteria={criteriaTemplateName}

Verify a phone number based on a criteria.

Each criteria has a defined verify and response parameters, set at the criteria creation api request. Verify request is based on the defined criteria for providing feedback regarding the requested phone number.

Example of a successful Verify response is shown at the code section at the right side of this page.

Unverified requests do not respect the defined parameter set in the response of the criteria, but they are using a default set of response parameters, aiming to explain to the customer the reason that the request was unverified. The unverified request response will always show the following four parameters:

  • requestId
  • verified
  • reason
  • reasonCode

Depending on the reason that the request is unverified, the following error codes and reasons will be sent back:

reasonCode Criterion reason
1001 ValidNumberFormat The number format is incorrect, and it is not matching the defined verification criteria
1101 activeNumber The number is flagged as not active, indicating that it is not currently in use or accessible for communication, and it is not matching defined verification criteria
1102 activeNumber The number is flagged as active, and it is not matching defined verification criteria
1201 numberType The number type is fixed, and it is not matching defined verification criteria
1202 numberType The number type is mobile, and it is not matching defined verification criteria
1203 numberType The number type is voip, and it is not matching defined verification criteria
1204 numberType The number type is premium rate, and it is not matching defined verification criteria
1205 numberType The number type is toll free, and it is not matching defined verification criteria
1206 numberType The number type is shared cost, and it is not matching defined verification criteria
1207 numberType The number type is unknown, and it is not matching defined verification criteria
1208 numberType The number type is unsupported type, and it is not matching defined verification criteria
1301 operatorCountry Mobile number operator country is not matching defined verification criteria
1401 mccMnc MCC – Mobile Country Code and MNC - Mobile Network Code are not matching defined verification criteria
2001 disposableNumber The number is flagged as non-disposable, non-temporary, and it is not matching defined verification criteria
2002 disposableNumber The number is flagged as disposable, temporary, and it is not matching defined verification criteria

Parameters

Name In Type Required Description
number path string true The phone number to be verified, given in the international format
criteriaTemplateName path string true Criteria template name

Example responses

200 Response

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "validNumberFormat": true,
  "activeNumber": true,
  "numberType": "mobile",
  "operatorName": "T-Mobile Czech Republic a.s.",
  "operatorCountry": "CZE",
  "mcc": "202",
  "mnc": "01",
  "disposableNumber": false,
  "verified": true
}

Responses

Status Meaning Description Schema
200 OK Valid request Inline
400 Bad Request Bad request / Invalid request parameters error400
401 Unauthorized Missing or Invalid API credentials error401
403 Forbidden Permission denied error403
404 Not Found Not Found error404
500 Internal Server Error Internal server error error500
Response Schema

Metadata

Metadata provides non functional information about the Verify service

Verify API Health

Code samples

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


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



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

};

fetch('https://api.tyntec.com/verify/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' => 'string',
  'apiKey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/verify/v1/health',
  params: {
  }, headers: headers

p JSON.parse(result)


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

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

}, headers = headers)

print(r.json())


<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('GET','https://api.tyntec.com/verify/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/verify/v1/health");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apiKey", "string");
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{"string"},
        "apiKey": []string{"API_KEY"},

    }

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

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

GET /health

Parameters

Name In Type Required Description
apiKey header string true API authentication key for the customer account

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 error403
404 Not Found Not Found error404

Verify API version

Code samples

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


GET https://api.tyntec.com/verify/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/verify/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/verify/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/verify/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/verify/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/verify/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/verify/v1/version", data)
    req.Header = headers

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

GET /version

Example responses

200 Response

{
  "version": "1.0.5"
}

Responses

Status Meaning Description Schema
200 OK Current API version versionResponse
403 Forbidden Permission denied error403
404 Not Found Not Found error404

Schemas

VerifyResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "validNumberFormat": true,
  "activeNumber": true,
  "numberType": "mobile",
  "operatorName": "T-Mobile Czech Republic a.s.",
  "operatorCountry": "CZE",
  "mcc": "202",
  "mnc": "01",
  "disposableNumber": false,
  "verified": true
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request
validNumberFormat boolean false none Is it valid phone number?
activeNumber boolean false none Is this number assigned to a subscriber?
numberType string false none Type of the phone number (mobile or fixed)
operatorName string false none Operator name
operatorCountry string false none The phone number's country of origin ISO3 code
mcc string false none MCC for given phone number
mnc string false none MNC for given phone number
disposableNumber boolean false none number is not disposable.
verified boolean false none The final status of the number verify.

ValidNumberFormatFalseResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "validNumberFormat is false.",
  "reasonCode": 1001
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none It is not a valid phone number.
reasonCode integer false none reason code when validNumberFormat is false.

ActiveNumberFalseResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "activeNumber is false.",
  "reasonCode": 1001
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none It is not an active phone number.
reasonCode integer false none reason code when activeNumber = false but configured Template as activeNumber = true

ActiveNumberTrueResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "activeNumber is true.",
  "reasonCode": 1102
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none This number is assigned to a subscriber.
reasonCode integer false none reason code when activeNumber = true but configured Template Criterion is activeNumber = false.

NumberTypeFixedResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "numberType is fixed.",
  "reasonCode": 1201
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none Type of the phone number (fixed)
reasonCode integer false none reason code when numberType = "fixed" but configured Template Criterion is numberType = "mobile".

NumberTypeMobileResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "numberType is mobile.",
  "reasonCode": 1202
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none Type of the phone number (mobile)
reasonCode integer false none reason code when numberType = "mobile" but configured Template Criterion is numberType = "fixed".

NumberTypeVoipResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "numberType is voip.",
  "reasonCode": 1203
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none Type of the phone number (voip)
reasonCode integer false none reason code when given phone number type is "voip", which is a unsupported number type.

NumberTypePremiumRateResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "numberType is premium_rate.",
  "reasonCode": 1204
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none Type of the phone number (premium_rate)
reasonCode integer false none reason code when given phone number type is "premium_rate", which is a unsupported number type.

NumberTypeTollFreeResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "numberType is toll_free.",
  "reasonCode": 1205
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none Type of the phone number (toll_free)
reasonCode integer false none reason code when given phone number type is "toll_free", which is a unsupported number type.

NumberTypeSharedCostResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "numberType is shared_cost.",
  "reasonCode": 1206
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none Type of the phone number (shared_cost)
reasonCode integer false none reason code when given phone number type is "shared_cost", which is a unsupported number type.

NumberTypeUnknownResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "numberType is unknown.",
  "reasonCode": 1207
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none Type of the phone number (unknown)
reasonCode integer false none reason code when given phone number type is "unknown", which is a unsupported number type.

RestUnsupportedNumberTypeResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "numberType is [value].",
  "reasonCode": 1208
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none Type of the phone number (rest unsupported number type)
reasonCode integer false none reason code for rest unsupported number type.

OperatorCountryMismatchResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "operatorCountry is [provided-number-country-name].",
  "reasonCode": 1301
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none The phone number's country of origin ISO3 code.
reasonCode integer false none reason code when number operatorCountry and configured Template criterion operatorCountry is a mismatch. For example, number operatorCountry = "DEU" but configured Template criterion operatorCountry = "USA".

MccMncMismatchResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "mccMnc is [provided-number-mccMnc-value].",
  "reasonCode": 1401
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none MCC and MNC for given phone number
reasonCode integer false none reason code when MCC and MNC for given phone number and configured Template criterion mccMnc is a mismatch. For example, number mccMnc = "26207" but configured Template criterion mccMnc = "21207".

DisposableNumberFalseResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "disposableNumber is false.",
  "reasonCode": 2001
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none number is not disposable.
reasonCode integer false none reason code when disposableNumber = false but configured Template Criterion is disposableNumber = true

DisposableNumberTrueResponse

{
  "requestId": "4457068c-194d-4f72-9550-13b81ec054a9",
  "verified": false,
  "reason": "disposableNumber is true.",
  "reasonCode": 2002
}

Properties

Name Type Required Restrictions Description
requestId string false none Unique ID of the request.
verified boolean false none The final status of the number verify.
reason String false none number is disposable.
reasonCode integer false none reason code when disposableNumber = true but configured Template Criterion is disposableNumber = false

CreateCriteria

{
  "name": "verify-criteria",
  "description": "provide criteria description",
  "criteria": [
    {
      "activeNumber": {
        "is": true
      }
    }
  ],
  "response": [
    "validNumberFormat",
    "numberType",
    "activeNumber",
    "operatorName",
    "operatorCountry",
    "mcc",
    "mnc",
    "disposableNumber"
  ]
}

Properties

Name Type Required Restrictions Description
name string false none Unique criteria name
description string false none none
criteria CriteriaIsAndBefore false none none
response CriteriaResponse false none none

ReturnCreatedCriteria

{
  "template": "verify-criteria",
  "message": "Created"
}

Properties

Name Type Required Restrictions Description
template string false none Unique criteria name
message string false none template creation status

UpdateCriteria

{
  "name": "verify-criteria",
  "description": "modified criteria description",
  "criteria": [
    {
      "activeNumber": {
        "is": true
      }
    }
  ],
  "response": [
    "operatorName",
    "operatorCountry",
    "mcc",
    "mnc"
  ]
}

Properties

Name Type Required Restrictions Description
name string false none Unique criteria name
description string false none none
criteria Criteria false none none
response Responses false none none

ReturnUpdatedCriteria

{
  "template": "verify-criteria",
  "message": "Updated"
}

Properties

Name Type Required Restrictions Description
template string false none Unique criteria name
message string false none template update status

RetrieveAllCriteria

{
  "id": "4457068c-194d-4f72-9550-13b81ec054a9",
  "name": "verify-criteria",
  "description": "provide criteria description",
  "criteria": [
    {
      "activeNumber": {
        "is": true
      }
    }
  ],
  "response": [
    "validNumberFormat",
    "numberType",
    "activeNumber",
    "operatorName",
    "operatorCountry",
    "mcc",
    "mnc",
    "disposableNumber"
  ]
}

Properties

Name Type Required Restrictions Description
id string false none Unique id for each criteria
name string false none Unique criteria name
description string false none none
criteria CriteriaIsInAndAfter false none none
response CriteriaResponse false none none

DeleteCriteria

{
  "template": "verify-criteria",
  "message": "Deleted"
}

Properties

Name Type Required Restrictions Description
template string false none Unique criteria name
message string false none template delete status

Criteria

[
  {
    "activeNumber": {
      "is": true
    }
  }
]

Properties

anyOf

Name Type Required Restrictions Description
anonymous IsCriteriaItem false none none

or

Name Type Required Restrictions Description
anonymous NumberTypeIsCriteriaItem false none none

or

Name Type Required Restrictions Description
anonymous OperatorCountryIsCriteriaItem false none none

CriteriaIsAndBefore

[
  {
    "activeNumber": {
      "is": true
    }
  }
]

Properties

anyOf

Name Type Required Restrictions Description
anonymous IsCriteriaItem false none none

or

Name Type Required Restrictions Description
anonymous NumberTypeIsCriteriaItem false none none

or

Name Type Required Restrictions Description
anonymous OperatorCountryIsCriteriaItem false none none

or

Name Type Required Restrictions Description
anonymous MccMncIsCriteriaItem false none none

CriteriaIsInAndAfter

[
  {
    "activeNumber": {
      "is": true
    }
  }
]

Properties

anyOf

Name Type Required Restrictions Description
anonymous IsCriteriaItem false none none

or

Name Type Required Restrictions Description
anonymous NumberTypeIsInCriteriaItem false none none

or

Name Type Required Restrictions Description
anonymous MccMncIsInCriteriaItem false none none

or

Name Type Required Restrictions Description
anonymous OperatorCountryIsInCriteriaItem false none none

IsCriteriaItem

{
  "activeNumber": {
    "is": true
  }
}

Properties

Name Type Required Restrictions Description
activeNumber object false none none
» is boolean false none criteria IS true

NumberTypeIsCriteriaItem

{
  "numberType": {
    "is": "mobile"
  }
}

Properties

Name Type Required Restrictions Description
numberType object false none none
» is string false none phone number type IS mobile.

NumberTypeIsInCriteriaItem

{
  "numberType": {
    "is_in": "mobile, fixed"
  }
}

Properties

Name Type Required Restrictions Description
numberType object false none none
» is_in string false none phone number type IS IN mobile or fixed.

OperatorCountryIsCriteriaItem

{
  "operatorCountry": {
    "is": "DEU"
  }
}

Properties

Name Type Required Restrictions Description
operatorCountry object false none none
» is string false none number IS in DEU.

OperatorCountryIsInCriteriaItem

{
  "operatorCountry": {
    "is_in": "NOR,SWE,FIN"
  }
}

Properties

Name Type Required Restrictions Description
operatorCountry object false none none
» is_in string false none number IS IN these countries.

MccMncIsCriteriaItem

{
  "mccMnc": {
    "is": "23202"
  }
}

Properties

Name Type Required Restrictions Description
mccMnc object false none none
» is string false none MCC and MNC IS equal to this specific value.

MccMncIsInCriteriaItem

{
  "mccMnc": {
    "is_in": "32452, 34567, 56748, 45628"
  }
}

Properties

Name Type Required Restrictions Description
mccMnc object false none none
» is_in string false none MCC and MNC IS IN this list.

CriteriaResponse

[
  "validNumberFormat",
  "numberType",
  "activeNumber",
  "operatorName",
  "operatorCountry",
  "mcc",
  "mnc",
  "disposableNumber"
]

Properties

None

Responses

[
  "operatorName",
  "operatorCountry",
  "mcc",
  "mnc"
]

Properties

None

healthResponse

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

Properties

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

versionResponse

{
  "version": "1.0.5"
}

Properties

Name Type Required Restrictions Description
version string false none none

error400

{
  "title": "400 Bad Request",
  "status": 400,
  "detail": "Invalid country(ies) code(s) provided"
}

Properties

Name Type Required Restrictions Description
title string false none Error of bad request
status integer false none HTTP error code
detail string false none Error message of bad request

error401

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

Properties

Name Type Required Restrictions Description
message string false none Unauthorized

error403

{
  "message": "You cannot consume this service"
}

Properties

Name Type Required Restrictions Description
message string false none Forbidden

error404

{
  "title": "Not Found",
  "status": 404,
  "message": "Requested path '/...' could not be found"
}

Properties

Name Type Required Restrictions Description
title string false none Error of bad request
status integer false none HTTP error code
message string false none Not Found

error409

{
  "title": "Conflict",
  "status": 409,
  "message": "Template <template_name> already exists"
}

Properties

Name Type Required Restrictions Description
title string false none Error of conflict
status integer false none HTTP error code
message string false none Conflict

error500

{
  "message": "Internal Server Error"
}

Properties

Name Type Required Restrictions Description
message string false none when something fails within the service.

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