Verify Overview

​

Verify Eligibility and Coverage

1. Direct Brands Only — Verify is offered to direct brands only. Resellers, Independent Software Vendors (ISVs), and aggregators or multi-tenant platforms are not eligible for Verify onboarding.
2. Pay-as-You-Go — Verify operates on a pay-as-you-go model, with no minimum spend commitments for the Verify product itself. Channel-level commitments may apply. Verify uses Plivo-registered Sender IDs to deliver OTP messages. While this setup works globally, some countries may experience reduced delivery quality and require independent Sender ID registration, which is subject to minimum commit requirements as per messaging guidelines.
3. India Delivery via ILDO — Plivo does not support SMS to India over domestic routes (DLT). Verify traffic to India will be sent via International Long Distance Operator (ILDO) routes, starting at USD 0.08 per message.

​

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 ${code})
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

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}")

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.verify_session.create({
    recipient: '<destination_number>',
    app_uuid: '<verify_app_uuid>',
    channel: 'sms',
    url: 'https://your-domain.com/callback',
    method: 'POST'
}).then(response => {
    console.log(`Session UUID: ${response.sessionUuid}`);
});

require 'plivo'

client = Plivo::RestClient.new('<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'
)

puts "Session UUID: #{response.session_uuid}"

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "<destination_number>",
    "app_uuid": "<verify_app_uuid>",
    "channel": "sms",
    "url": "https://your-domain.com/callback",
    "method": "POST"
  }'

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

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}")

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.verify_session.validate({
    id: '<session_uuid>',
    otp: '<otp_code>'
}).then(response => {
    console.log(`Status: ${response}`);
});

require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

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

puts "Status: #{response}"

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/{session_uuid}/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"otp": "<otp_code>"}'

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'
)

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+14155551234",
    "app_uuid": "<verify_app_uuid>",
    "channel": "voice"
  }'

​

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"

const plivo = require('plivo');
const express = require('express');
const app = express();

app.post('/receive_callback/', (req, res) => {
    const auth_token = '<auth_token>';
    const signature = req.get('X-Plivo-Signature-V2');
    const nonce = req.get('X-Plivo-Signature-V2-Nonce');
    const url = req.protocol + '://' + req.get('host') + req.originalUrl;

    const isValid = plivo.validateSignature(url, nonce, signature, auth_token);
    console.log('Signature valid:', isValid);

    res.send('OK');
});

require 'sinatra'
require 'plivo'

get '/receive_callback/' do
    auth_token = "<auth_token>"
    signature = request.env["HTTP_X_PLIVO_SIGNATURE_V2"]
    nonce = request.env["HTTP_X_PLIVO_SIGNATURE_V2_NONCE"]
    uri = request.url.split("?")[0]

    is_valid = Plivo::Utils.valid_signature?(uri, nonce, signature, auth_token)
    puts "Signature valid: #{is_valid}"

    "OK"
end

package main

import (
    "fmt"
    "net/http"
    "github.com/plivo/plivo-go/v7"
)

func handler(w http.ResponseWriter, r *http.Request) {
    url := "https://" + r.Host + r.URL.Path
    authToken := "<auth_token>"
    signature := r.Header.Get("X-Plivo-Signature-V2")
    nonce := r.Header.Get("X-Plivo-Signature-V2-Nonce")

    isValid := plivo.ValidateSignatureV2(url, nonce, signature, authToken)
    fmt.Printf("Signature valid: %v\n", isValid)
}

​

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