Verify API - Verification policy and fallback time

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page explains how to use the verification_policy parameter in the POST request. The verification policy is an ordered set of verification methods and their fallback times.

📘

NOTE:

Contact our sales team for availability of supported verification methods in your region.

Usage restrictions

To ensure a consistent end user experience and a clean technical solution, the following limitations apply:

• Silent Verify and Push Verify can't be used in the same verification policy.
• If either Silent Verify or Push Verify is included, it must be the first in the policy, followed by OTP based methods. OTP based methods are SMS, WhatsApp, Viber, RCS, and email.
• A maximum of three methods can be specified in the policy.
• The fallback time has to be greater than 30 seconds.

Default verification methods and fallback times

The default verification method is SMS with a 60-second fallback time. If the verification_policy is not included in your request and there is no fixed routing configured for that country, SMS is sent as the default method.

If a fallback time is not specified, the following fallback times apply:

For adjustments to the default fallback times, contact our Customer Support Team.

Examples

Valid verification policy

In this example, the default fallback time of 60 seconds will be applied to WhatsApp, since it is not specified.

{
  "verification_policy": [
    {
      "method": "push",
      "fallback_time": 30
    },
    {
      "method": "whatsapp",
    },
    {
      "method": "viber",
      "fallback_time": 120
    }
  ]
}

Valid verification policy

If both Silent Verify and RCS methods fail, no further methods are used.

{  
  "verification_policy": [
    {
      "method": "silent",
      "fallback_time": 30
    },
    {
      "method": "rcs",
      "fallback_time": 45
    }
  ]
}

Invalid verification policy

This policy is invalid because the order of verification methods is incorrect. If Silent Verify or Push Verify methods are used, they must be listed as the first verification method. Placing them later in the sequence does not serve any practical purpose.

{  
  "verification_policy": [
    {
      "method": "whatsapp",
      "fallback_time": 30
    },
    {
      "method": "silent",
      "fallback_time": 30
    }
  ]
}

Invalid verification policy

The policy is invalid because it combines Silent Verify and Push Verify.

{  
  "verification_policy": [
    {
      "method": "silent",
      "fallback_time": 45
    },
    {
      "method": "push"
    }
  ]
}