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.

Default verification method

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.

Usage restrictions

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

• Silent Verify, Push Verify, and QR Verify can't be used in the same verification policy.
• If Silent Verify, Push Verify, or QR 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 verification methods can be specified in the policy.

Fallback restrictions

• Use the fallback_time parameter to set the fallback time for each verification method.
• The fallback time has to be greater than 30 seconds.
• The maximum allowed time is 300 seconds (5 minutes) for the verification attempt to complete. This total time applies to all channels chosen, whether in the fallback policy or configured in your account (the choice of channel and fallback by country). Each channel's time and the allotted time for all channels can't add up to greater than five minutes. If the verification attempt is not completed before the assigned expiration time ends, the transaction will fail.

Example of a response when the total time elapsed is greater than five minutes:

{
  "created_on": "2025-05-06T08:54:29.543000Z",
  "inner_methods": [
    {
      "err_code": 3056,
      "err_msg": "Message failed to deliver in specified fallback time.",
      "method": "sms",
      "state": "FAILED",
      "tried_on": "2025-05-06T08:54:29.565000Z",
      "updated_on": "2025-05-06T08:59:30.005000Z"
    }
  ],
  "recipient": {
    "phone_number": "11234567890"
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "state": "FAILED",
  "updated_on": "2025-05-06T08:59:30.005000Z",
  "verification_policy": [
    {
      "method": "sms",
      "fallback_time": 300
    }
  ]
}

Default fallback time for each channel

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 - incorrect order

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 - combination

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

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