Latest Legacy

List all sessions

This API retrieves a list of sessions based on a filter criteria over the last 90 days.

Note: The default rate limit for this API is 20 requests per minute. If the rate limit is exceeded, the API will throw the error “too many requests”.

API Endpoint

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

Arguments

app_uuid string

Filters results based on sessions sent using a specific application.

status string

Filter results by the current status of a session. Allowed values: in-progress,verified,expired

recipient string

Filters results by the number to which codes/OTPs were sent using Plivo APIs. You can filter the details by using the exact number in E.164 format — for example, +12025553434.

subaccount string

Filters for sessions sent using a specific subaccount’s Auth Token.

limit string

Denotes the number of results per page. The maximum number of results that can be fetched is 20.

Defaults to 20.

offset string

Denotes the number of value items by which the results should be offset. Defaults to 0. Read more about offset-based pagination.

session_time string

Filters sessions based on the time the session was initiated.

Timestamps are expected to be in YYYY-MM-DD HH:MM[:ss[.uuuuuu]] format, and are considered to be in UTC time zone.

If you do not specify this attribute, the sessions for the last 24 hours will be retrieved by default.

The filter can be used in five forms:

session_time: Use this argument to filter for session by exact timestamp. The format expected is YYYY-MM-DD HH:MM:ss:uuuuuu. To get all sessions that were sent or received at 2021-03-21 11:47:30.982811, use session_time=2021-03-21 11:47:30.982811
session_time__gt: gt stands for greater than. Use this argument to filter for sessions initiated after a given time. To get all session that were initiated after 2021-03-21 11:47, use session_time__gt=2021-03-21 11:47
session_time__gte: gte stands for greater than or equal to. To get all sessions that were initiated after or exactly at 2021-03-21 11:47[:30], use session_time__gte=2021-03-21 11:47[:30]
session_time__lt: lt stands for less than. Use this argument to filter for sessions initiated before a given time. To get all sessions that were initiated before 2021-03-21 11:47, use session_time__lt=2021-03-21 11:47
session_time__lte: lte stands for less than or equal to. To get all sessions that were initiated before or exactly at 2012-03-21 11:47[:30], use session_time__lte=2012-03-21 11:47[:30]
brand_namestring

Filters and lists all the sessions based on the specific brands that were passed in the session creation API.

app_hashstring

Filters and lists all the sessions based on the app hashes that were passed in the session creation API.

Note: The subaccount filter is implicitly applied when a subaccount’s API credentials are used to fire this API. This argument should be used only when the parent account’s API credentials are used to fire this API.

Returns

This API returns a list of sessions matching the filters specified in the request.

The API response also contains a meta field with the fields:

  • limit: the size of the page returned in the response
  • offset: the offset for the page returned in the response
  • next: the URL that points to the next page of results
  • previous: the URL that points to the previous page of results

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": [
               {
                   "channel": "sms",
                   "attempt_uuid": "bd460457-6c2f-4177-a879-e6a83c35d5a9",
                   "status": "undelivered",
                   "time": "2023-06-01T10:40:05.804031Z"
               }
           ],
           "charges": {
               "total_charge": "0.08",
               "validation_charge": "0.0000",
               "attempt_charges": [
                   {
                       "attempt_uuid": "bd460457-6c2f-4177-a879-e6a83c35d5a9",
                       "channel": "sms",
                       "charge": "0.08000"
                   }
               ]
           },


           "created_at": "2023-06-01T10:40:05.804031Z",
           "updated_at": "2023-06-01T10:40:05.804031Z"
       },


            {
           "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"
               },
               {
                   "channel": "voice",
                   "attempt_uuid": "04a81620-c4ab-45d6-847d-cc3ae6fec121",
                   "status": "EARLY MEDIA",
                   "time": "2023-06-01T08:53:25.577153Z"
               }
           ],
           "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"
                   },
                   {
                       "attempt_uuid": "04a81620-c4ab-45d6-847d-cc3ae6fec121",
                       "channel": "voice",
                       "charge": "0.00000"
                   }
               ]
           },
           "created_at": "2023-06-01T08:52:39.363253Z",
           "updated_at": "2023-06-01T08:53:25.577153Z"
       } 
       ] 
}

Example Request

1
2
3
4
5
6
7
8
9
10
11
import sys
sys.path.append("../plivo-python")
import plivo

client = plivo.RestClient()

response = client.verify_session.list(
limit=2,
        	offset=6)

print(response)
1
2
3
4
5
6
7
8
9
10
11
12
require "rubygems"
require "/usr/src/app/lib/plivo.rb"
include Plivo
#Environment
api = RestClient.new("<auth_id>", "<auth_token>")
begin
     puts("List all Sessions")
     response = api.verify_session.list(limit:1,offset:0)
     puts response
rescue PlivoRESTError => e
     puts 'Exception: ' + e.message
end  
1
2
3
4
5
6
let plivo = require('plivo')
let client = new plivo.Client('<auth_id>', '<auth_token>');
client.verify_session.list().then(function(response) {
let formattedResponse = JSON.stringify(response, null, 2);
console.log(formattedResponse)
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
require '/usr/src/app/vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoResponseException;

// ENVIRONMENT
$client = new RestClient("<auth_id>", "<auth_token>");


// List all sessions
try {
$response = $client->verifySessions->list(['limit' => '5','offset' => 0]);
print_r($response);
}
catch (Exception $ex) {
print_r($ex);
}

?>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import java.io.IOException;
import java.net.URL;
import java.util.Collections;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.verify_session.VerifySession;
import com.plivo.api.models.verify_session.VerifySessionList;
import com.plivo.api.models.verify_session.SessionCreateResponse;
import com.plivo.api.models.message.Message;
import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.models.base.ListResponse;
class Session {
  public static void main(String[] args) throws PlivoValidationException {
    Plivo.init("<auth_id>", "<auth_token>");
   try
    {
      ListResponse<VerifySessionList> response = VerifySession.lister()
        .limit(1)
        .offset(0)
        .list();
    System.out.println(response);
}
    catch (Exception e)
    {
      e.printStackTrace();
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;
namespace dotnet_sdk
{
    class Session
    {
        static void Main(string[] args)
        {
            // ENVIRONMENT
            var api = new PlivoApi("<auth_id>", "<auth_token>");             
            // List all Sessions
             try
             {   
                Console.WriteLine("List all Sessions");
                var response = api.VerifySession.List(limit:1,offset:0);
                Console.WriteLine(response);
             }
catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }

}
}
}
1
2
curl -i --user auth_id_ID:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
package main

import (
"fmt"
"encoding/json"

"github.com/plivo/plivo-go"
)

func main() {
client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
if err != nil {
fmt.Printf("Error:\n", err)
}

//List details of all sessions for the account with filter params
response_list, err := client.VerifySession.List(
plivo.SessionListParams{
Limit: 1,
Offset:2,
},
)
if err != nil {
fmt.Print("Error", err.Error())
return
}
res2, _ := json.Marshal(response_list)
fmt.Printf("Response: \n\n %#v \n", string(res2))

}