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

string

A 36-character string that uniquely identifies a session.

string

ID of the application used to trigger the session.

string

Alias of the Verify application used to trigger the session.

string

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

string

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

string

Carrier network detected for the destination number.

string

IP address from which the session creation request originated.

string

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

string

The last channel used for the session.

string

Language translation used for the session.

object

Details of all attempts made during a session.

object

Details of all charges incurred during a session.

string

UTC time when the session was created.

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

string

required

The phone number to send the OTP to.

string

UUID of the Verify application. Defaults to default application.

string

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

string

URL for status callbacks.

string

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

string

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

string

Brand name to replace ${brand_name} in templates.

string

Android app hash for SMS Retriever API integration.

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

string

Unique identifier for the API request.

string

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

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

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

string

Unique identifier for the API request.

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

string

Unique identifier for the API request.

string

A 36-character string that uniquely identifies a session.

string

ID of the application used to trigger the session.

string

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

string

The last channel used for the session.

string

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

array

Details of all attempts made during the session.

object

Details of all charges incurred during the session.

string

UTC time when the session was created.

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

string

Filter by application UUID.

string

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

string

Filter by destination number (E.164 format).

string

Filter by subaccount.

integer

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

integer

Number of results to skip. Default: 0.

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.

string

Filter by brand name.

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

string

Unique identifier for the API request.

object

Pagination metadata: limit (results per page), offset (items skipped), and next/previous page URLs.

array

Array of session objects — see The Session Object.

{
    "api_id": "3a7a0d6d-1b85-4593-921c-373e673a5799",
    "meta": {
        "limit": 20,
        "offset": 0,
        "next": null,
        "previous": null
    },
    "sessions": [
        {
            "session_uuid": "51e965f3-65a5-4ca0-9542-57154118a991",
            "app_uuid": "59728519-d145-45d6-8d46-60c06f7e8bbb",
            "recipient": "918681951370",
            "channel": "sms",
            "status": "expired",
            "count": 1,
            "attempt_details": [...],
            "charges": {...},
            "created_at": "2023-06-01T10:40:05.804031Z",
            "updated_at": "2023-06-01T10:40:05.804031Z"
        }
    ]
}

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

string

Unique session identifier.

string

Session status. Values: in-progress, expired.

string

Unique identifier for the SMS/call attempt.

string

Sequence number of the attempt.

string

Channel used. Values: sms, voice.

string

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

string

Error code from the channel.

string

Destination phone number.

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