Verify

Hi there!

Thanks for using tyntec’s  Phone Verification API. This guide is to help you get started quickly by showing you how to verify your first number to determine validity, reachability and fraud risk. It will walk you through your first API request and interpretation of the response, complete with basic support for troubleshooting if something goes wrong.

To verify phone numbers, you make an HTTP GET request to tyntec’s Phone Verification API.

• tyntec Business Center account
• Generated API Key from the Business Center
• Installed Postman to test API requests

    1. Authorize your API calls by adding the HTTP header apiKey with your API key that you’ve got from your Business Center.rexx

    2.  Create new Postman collection and GET request, configure Authorization section of request:

• set Key -> apiKey
• set Value -> <your key>

Use the following endpoint to check how reachable and trustworthy the given phone number is.

In Postman example:

• Ensure method is set to GET
• Set number {phoneNumber} with correct prefix format
• Click on Send button to call request

Response is synchronous – it means the result is immediately returned according to the schema defined in API references – NumberResponse.

validNumberFormat determines if the phone number, entered into forms by users or auto dialers, is valid according to the numbering plan for that country.

A phone number is considered active when the number is assigned by the home network operator to a subscriber.

Type of the phone number is defined in field numberType with possible enum values: 
fixed, mobile, fixed_or_mobile, mvno_gsm, iden, cdma, gsm_cdma, toll_free, premium_rate, shared_cost, voip, personal, pager, uan, voicemail, unknown.

It identifies the name and the country of the home network operator who has provided the phone number to a subscriber.

Boolean value to determine whether an SMS can be delivered to the subscriber behind the phone number. If outreachReady is “True”, the phone number format is valid, active and reachable via texting.

Phone Verification service aims to provide information regarding the validity, reachability and trustworthiness of a phone number. This information comes in the form of a Risk Index about the phone number. The following risk classifications for field fraudRisk are applied:

• High: The phone number is considered a high-risk number and the API user should avoid contacting this number.
• Medium: The phone number is generally considered a legitimate number, but the API user should exercise caution when contacting this number for sensitive data or high-value transactions.
• Low: The phone number is considered a legitimate, trustworthy number and the API user should feel confident to contact this number.
• Unknown: Validation service was not able to assess fraud risk of the phone number because of technical reasons or insufficient data.

Based on the risk classification you can evaluate the level of engagement and transaction with the subscriber behind the given number.

A Phone Verification API call could end with error in case there is a problem with your API key or internal server infrastructure, these problems could be identified with specific error codes and responses:

• 401 – Not present API Key or incorrect header parameter used.
• 403 – Incorrect API Key or permission to key not granted.
• 500 – Internal server error.

To debug server availability, you can call endpoint /health to retrieve current server status and double check if the problem is on the server or client (request) side.

Postman example shows server is up and running with status “up”.