Session API

The Session API lets you send and validate one-time passwords (OTP) for two-factor authentication (2FA) using SMS and voice channels. API Endpoint

https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/

The Session Object

The API creates a Session object once for each recipient within the code expiry time. A session can have multiple attempts to deliver the OTP.

Attributes

session_uuid

string

A 36-character string that uniquely identifies a session.

app_uuid

string

ID of the application used to trigger the session.

alias

string

Alias of the Verify application used to trigger the session.

recipient

string

The destination phone number (in E.164 format).

destination_country_iso2

string

ISO 3166-1 alpha-2 country code of the destination number. Example: IN.

destination_network

string

Carrier network detected for the destination number.

requestor_ip

string

IP address from which the session creation request originated.

status

string

Current status. Values: in-progress, verified, expired.

channel

string

The last channel used for the session.

locale

string

Language translation used for the session.

otp_attempts

object

Details of all attempts made during a session.

charge

object

Details of all charges incurred during a session.

created_at

string

UTC time when the session was created.

updated_at

string

UTC time when the session was last updated.

Create a Session

Send an OTP via SMS or voice.

POST https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/

Arguments

recipient

string

required

The phone number to send the OTP to.

app_uuid

string

UUID of the Verify application. Defaults to default application.

channel

string

Delivery channel. Values: sms, voice. Default: sms.

url

string

URL for status callbacks.

method

string

HTTP method for callbacks. Values: GET, POST. Default: POST.

locale

string

Language code (e.g., en_US, es, fr_FR). Default: en.

brand_name

string

Brand name to replace ${brand_name} in templates.

app_hash

string

Android app hash for SMS Retriever API integration.

code_length

integer

OTP length (4-8). Overrides application default.

Example

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(response)

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(response);
});

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 response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->verifySessions->create(
    '<destination_number>',
    [
        'app_uuid' => '<verify_app_uuid>',
        'channel' => 'sms',
        'url' => 'https://your-domain.com/callback',
        'method' => 'POST'
    ]
);

print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.verify_session.VerifySession;
import com.plivo.api.models.verify_session.SessionCreateResponse;

Plivo.init("<auth_id>", "<auth_token>");

SessionCreateResponse response = VerifySession.creator(
    "<verify_app_uuid>",
    "<destination_number>",
    "sms",
    "https://your-domain.com/callback",
    "POST"
).create();

System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.VerifySession.Create(
    recipient: "<destination_number>",
    app_uuid: "<verify_app_uuid>",
    channel: "sms",
    url: "https://your-domain.com/callback",
    method: "POST"
);

Console.WriteLine(response);

package main

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

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.VerifySession.Create(plivo.SessionCreateParams{
        Recipient: "<destination_number>",
        AppUUID:   "<verify_app_uuid>",
        Channel:   "sms",
        URL:       "https://your-domain.com/callback",
        Method:    "POST",
    })

    fmt.Println(response)
}

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

Response

api_id

string

Unique identifier for the API request.

message

string

Status of the request. Returns Session initiated on successful session creation.

session_uuid

string

A 36-character string that uniquely identifies a session.

{
    "api_id": "3335cb16-d297-4e00-a5e6-66d2bb03b323",
    "message": "Session initiated",
    "session_uuid": "8e712097-8090-4644-81e7-8f4265d8354e"
}

Validate a Session

Validate the OTP entered by the user.

POST https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/{session_uuid}/

Arguments

otp

string

required

The OTP to validate.

You can attempt no more than 10 validations per session to prevent brute-force attacks.

Example

import plivo

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

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

print(response)

const plivo = require('plivo');

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

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

require 'plivo'

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

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

puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->verifySessions->validate('<session_uuid>', '<otp_value>');

print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.verify_session.VerifySession;

Plivo.init("<auth_id>", "<auth_token>");

SessionCreateResponse response = VerifySession.validation(
    "<session_uuid>",
    "<otp_value>"
).create();

System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.VerifySession.Validate(
    session_uuid: "<session_uuid>",
    otp: "<otp_value>"
);

Console.WriteLine(response);

package main

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

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.VerifySession.Validate(
        plivo.SessionValidationParams{OTP: "<otp_value>"},
        "<session_uuid>",
    )

    fmt.Println(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_value>"}'

Response

api_id

string

Unique identifier for the API request.

message

string

Status of the request. Returns session validated successfully. on a successful validation.

{
    "api_id": "e7af31b5-a7cb-40d6-a3ab-122fdcc9f0fe",
    "message": "session validated successfully."
}

Retrieve a Session

Get details of a specific session.

GET https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/{session_uuid}/

Example

import plivo

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

response = client.verify_session.get('<session_uuid>')

print(response)

const plivo = require('plivo');

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

client.verify_session.get('<session_uuid>').then(response => {
    console.log(response);
});

require 'plivo'

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

response = client.verify_session.get('<session_uuid>')

puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->verifySessions->get('<session_uuid>');

print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.verify_session.VerifySession;

Plivo.init("<auth_id>", "<auth_token>");

VerifySession response = VerifySession.getter("<session_uuid>").get();

System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.VerifySession.Get("<session_uuid>");

Console.WriteLine(response);

package main

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

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.VerifySession.Get("<session_uuid>")

    fmt.Println(response)
}

curl "https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/{session_uuid}/" \
  -u '<auth_id>:<auth_token>'

Response

api_id

string

Unique identifier for the API request.

session_uuid

string

A 36-character string that uniquely identifies a session.

app_uuid

string

ID of the application used to trigger the session.

recipient

string

The destination phone number (in E.164 format).

channel

string

The last channel used for the session.

status

string

Current status. Values: in-progress, verified, expired.

attempt_details

array

Details of all attempts made during the session.

charges

object

Details of all charges incurred during the session.

created_at

string

UTC time when the session was created.

updated_at

string

UTC time when the session was last updated.

{
    "api_id": "abf7fc2b-fac5-471c-9592-74ed6834b5e6",
    "session_uuid": "60ea68db-b123-46d9-9eb2-1201d516dbbd",
    "app_uuid": "ec66515e-86f6-4507-8620-31c039538d7a",
    "recipient": "919380013443",
    "channel": "voice",
    "status": "Expired",
    "count": 3,
    "attempt_details": [
        {
            "channel": "voice",
            "attempt_uuid": "90cc6cde-db80-4d14-9716-3aaa2b403377",
            "status": "answer",
            "time": "2023-06-01T08:52:39.363253Z"
        },
        {
            "channel": "sms",
            "attempt_uuid": "acbffc94-283b-42b3-8a96-65cbc18a9624",
            "status": "delivered",
            "time": "2023-06-01T08:52:59.484375Z"
        }
    ],
    "charges": {
        "total_charge": "0.113",
        "validation_charge": "0.0000",
        "attempt_charges": [
            {
                "attempt_uuid": "90cc6cde-db80-4d14-9716-3aaa2b403377",
                "channel": "voice",
                "charge": "0.03300"
            },
            {
                "attempt_uuid": "acbffc94-283b-42b3-8a96-65cbc18a9624",
                "channel": "sms",
                "charge": "0.08000"
            }
        ]
    },
    "created_at": "2023-06-01T08:52:39.363253Z",
    "updated_at": "2023-06-01T08:53:25.577153Z"
}

List All Sessions

Retrieve a list of sessions based on filter criteria over the last 90 days.

GET https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/

The default rate limit is 20 requests per minute. Exceeding this limit returns “too many requests” error.

Query Parameters

app_uuid

string

Filter by application UUID.

status

string

Filter by status. Values: in-progress, verified, expired.

recipient

string

Filter by destination number (E.164 format).

subaccount

string

Filter by subaccount.

limit

integer

Results per page. Max: 20. Default: 20.

offset

integer

Number of results to skip. Default: 0.

session_time

string

Filter by session initiation time. Format: YYYY-MM-DD HH:MM. Supports variants: session_time__gt, session_time__gte, session_time__lt, session_time__lte.

brand_name

string

Filter by brand name.

app_hash

string

Filter by app hash.

Example

import plivo

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

response = client.verify_session.list(limit=10, offset=0)

print(response)

const plivo = require('plivo');

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

client.verify_session.list().then(response => {
    console.log(response);
});

require 'plivo'

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

response = client.verify_session.list(limit: 10, offset: 0)

puts response

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->verifySessions->list(['limit' => 10, 'offset' => 0]);

print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.verify_session.VerifySession;

Plivo.init("<auth_id>", "<auth_token>");

ListResponse<VerifySessionList> response = VerifySession.lister()
    .limit(10)
    .offset(0)
    .list();

System.out.println(response);

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.VerifySession.List(limit: 10, offset: 0);

Console.WriteLine(response);

package main

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

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.VerifySession.List(plivo.SessionListParams{
        Limit:  10,
        Offset: 0,
    })

    fmt.Println(response)
}

curl "https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/?limit=10&offset=0" \
  -u '<auth_id>:<auth_token>'

Response

api_id

string

Unique identifier for the API request.

Status Callbacks

Set up a server endpoint to receive real-time status updates for your verification sessions. Specify the callback URL when creating a session.

Callback Attributes

SessionUUID

string

Unique session identifier.

SessionStatus

string

Session status. Values: in-progress, expired.

AttemptUUID

string

Unique identifier for the SMS/call attempt.

AttemptSequence

string

Sequence number of the attempt.

Channel

string

Channel used. Values: sms, voice.

ChannelStatus

string

Attempt status. SMS: queued, sent, delivered, failed, undelivered. Voice: in-progress, completed, ringing.

ChannelErrorCode

string

Error code from the channel.

Recipient

string

Destination phone number.

RequestTime

string

UTC time when the attempt was created.

Callback Behavior

Plivo automatically retries webhooks three times if HTTP 200 is not returned:

First retry: 60 seconds after original attempt
Second retry: 120 seconds after first retry
Third retry: 240 seconds after second retry

Overview - Quick start guide and concepts

Concepts

API Reference

The Session Object

Attributes

Create a Session

Arguments

Example

Response

Validate a Session

Arguments

Example

Response

Retrieve a Session

Example

Response

List All Sessions

Query Parameters

Example

Response

Status Callbacks

Callback Attributes

Callback Behavior

​The Session Object

​Attributes

​Create a Session

​Arguments

​Example

​Response

​Validate a Session

​Arguments

​Example

​Response

​Retrieve a Session

​Example

​Response

​List All Sessions

​Query Parameters

​Example

​Response

​Status Callbacks

​Callback Attributes

​Callback Behavior

​Related

The Session Object

Attributes

Create a Session

Arguments

Example

Response

Validate a Session

Arguments

Example

Response

Retrieve a Session

Example

Response

List All Sessions

Query Parameters

Example

Response

Status Callbacks

Callback Attributes

Callback Behavior

Related