Verify Overview

​

Quick Start

1

Set Up an Application in Plivo Console

To start sending OTPs, create a Verify application in the Plivo Console.Configure these settings:

Setting	Description
Alias	Friendly name for your application
Brand name	Your brand name shown in messages
Code length	Number of digits in the OTP (4-8)
Expiry	Time window before the OTP expires
Attempts	Maximum delivery attempts per session
Template	Message template (e.g., “Your ${brand} verification code is$“)
Android AppHash	Hash string for automatic SMS verification on Android

Once created, you’ll receive an Application UUID to use in API requests.

2

Create a Session to Send OTPs

Use the Create Session API to send an OTP:

Python

Node.js

Ruby

cURL

Copy

Ask AI

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.verify_session.create(
    recipient='<destination_number>',
    app_uuid='<verify_app_uuid>',
    channel='sms',
    url='https://your-domain.com/callback',
    method='POST'
)

print(f"Session UUID: {response.session_uuid}")

Set a callback URL to receive real-time delivery status updates.

3

Validate the OTP

When the user enters the OTP, validate it using the Validate Session API:

Python

Node.js

Ruby

cURL

Copy

Ask AI

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.verify_session.validate(
    session_uuid='<session_uuid>',
    otp='<otp_code>'
)

print(f"Status: {response.message}")

4

Handle the Response

If the OTP is valid, allow the user to proceed. If invalid, prompt them to re-enter or resend the OTP.

​

Channels: SMS vs Voice

​

Using Voice OTP

response = client.verify_session.create(
    recipient='+14155551234',
    app_uuid='<verify_app_uuid>',
    channel='voice',  # Voice call instead of SMS
    url='https://your-domain.com/callback'
)

​

Channel Fallback Strategy

# Try SMS first
response = client.verify_session.create(
    recipient=phone,
    app_uuid=app_uuid,
    channel='sms'
)

# If SMS fails or times out, retry with voice
if response.status == 'failed':
    response = client.verify_session.create(
        recipient=phone,
        app_uuid=app_uuid,
        channel='voice'
    )

​

Sessions

​

Session Lifecycle

1. Created - OTP generated and first delivery attempted
2. In Progress - Waiting for user to enter OTP (additional attempts possible)
3. Verified - User entered correct OTP
4. Expired - Session timed out without successful validation

​

Fraud Shield

​

Protection Levels

​

Preventing False Positives

1. Skip fraud check for trusted users - Set check_fs=false for known good users
2. Create separate apps - Use different apps for Sign Up, Sign In, and Password Reset
3. Use a dedicated low-protection app - For trusted user segments, create an app with Fraud Shield set to Low or Disabled

​

Signature Validation

​

HTTP Headers

• X-Plivo-Signature-V2 - Generated using account/subaccount Auth Token
• X-Plivo-Signature-Ma-V2 - Always generated using main account Auth Token
• X-Plivo-Signature-V2-Nonce - Unique nonce for the request

​

Generating the Signature

• Key: Your Plivo Auth Token
• Message: Base URI + X-Plivo-Signature-V2-Nonce (e.g., https://yourdomain.com/callback/05429567804466091622)
• Hash function: SHA256

​

Example

from flask import Flask, request
import plivo

app = Flask(__name__)

@app.route('/receive_callback/', methods=['POST'])
def validate():
    signature = request.headers.get('X-Plivo-Signature-V2')
    nonce = request.headers.get('X-Plivo-Signature-V2-Nonce')
    uri = request.url
    auth_token = "<auth_token>"

    is_valid = plivo.utils.validate_signature(uri, nonce, signature, auth_token)
    print(f"Signature valid: {is_valid}")

    return "OK"

​

Translation Support

1. Contact Plivo support to configure translations for your SMS templates
2. Pass the locale parameter when creating a session

​

Locale Format

• en - English
• en_US - English (US)
• es - Spanish
• fr_FR - French (France)

​

When to Use Multiple Applications

• Different OTP lengths are needed (e.g., 4-digit for login, 6-digit for checkout)
• Different channels are required (SMS-only for logins, SMS+voice for payments)
• Different Fraud Shield settings are needed per use case

​

Reporting

​

Session Logs

​

Filters

​

Related

• Session API Reference - Full API documentation
• API Overview - Authentication and request format