Skip to main content
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.
​
recipient
string
The destination phone number (in E.164 format).
​
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)

​
Response

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

​
Response

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

​
Response

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

​
Response

{
    "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

​
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