Link Search Menu Expand Document

Prevail API: Session Requests

Submit Session Requests

POST https://prevail.ai/api/v1/session_requests

Submits a new Session request. The Prevail Scheduling Team reviews all requested Sessions before they are scheduled. If your Organization has Self-Service enabled, you can directly schedule Sessions, without the assistance of Prevail Staff.

To determine when a Session has been scheduled and obtain the Session’s join URL, retrieve a list of Session requests using the GET /session_requests endpoint.

Authorization

Bearer Token {{jwt_signed}}

Used to authenticate the request. Replace with your access token.

Headers

Content-Type application/json

Specifies the format of the request body.

Accept application/json

Specifies the expected format of the response body.

Example Request

When you create a new Session through the API, the response includes system‑generated fields that let you track its status. Immediately after submission, session_state is assigned the value initial, indicating the request is awaiting review by Prevail Staff; at this stage, both session_url and remote_session_id remain null. Once Prevail Staff schedules the session, session_state changes to scheduled and the session_url and remote_session_id fields are populated. When the session officially begins, session_state is updated to active.

Field Value Description
session_state initial Session Request is created and awaiting review by the Prevail Scheduling Team. The session_url and remote_session_id are null.
session_state scheduled Session is scheduled. Applies to Organizations that submit Session requests. The Session join URL and remote_session_id are assigned.
session_state ready Session is scheduled. Applies to self-service Organizations. The Session join URL and remote_session_id are assigned.
session_state active Session is in progress. Participants can join using the Session join URL.
session_state canceled Session was canceled. The Session join URL is disabled and participants can no longer join.
cURL 
curl -X POST "https://prevail.ai/api/v1/sessions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "session_request": {
        "invites": ["quartz@example.com", "obsidian@example.com"],
        "deponent": {
            "name": "Malachite Yarrow",
            "email": "malachite@example.com",
            "role": "deponent"
        },
        "remote_session": {
            "title": "Example Remote Session Request",
            "case": "567-case-id-name",
            "start_date": "2025-01-28",
            "start_time": "01:30 AM",
            "time_zone": "Pacific Time (US & Canada)",
            "estimated_duration": 1.25
        },
        "session_details": {
            "additional_details": "",
            "preferred_manager": "Quartz Verbena",
            "video_provider": "chime",
            "session_type": "remote_deposition"
        },
        "postback_url": "https://www.urltosendsessioninfo.com"
    }
}'
JavaScript 
// Create a session using fetch API
const sessionData = {
  session_request: {
    invites: ["quartz@example.com", "obsidian@example.com"],
    deponent: {
      name: "Malachite Yarrow",
      email: "malachite@example.com",
      role: "deponent"
    },
    remote_session: {
      title: "Example Remote Session Request",
      case: "567-case-id-name",
      start_date: "2025-01-28",
      start_time: "01:30 AM",
      time_zone: "Pacific Time (US & Canada)",
      estimated_duration: 1.25
    },
    session_details: {
      additional_details: "",
      preferred_manager: "Quartz Verbena",
      video_provider: "chime",
      session_type: "remote_deposition"
    },
    postback_url: "https://www.urltosendsessioninfo.com"
  }
};

const response = await fetch('https://prevail.ai/api/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify(sessionData)
});

const data = await response.json();
console.log(data);
Python 
import requests
import json

url = 'https://prevail.ai/api/v1/sessions'

headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

session_data = {
    "session_request": {
        "invites": ["quartz@example.com", "obsidian@example.com"],
        "deponent": {
            "name": "Malachite Yarrow",
            "email": "malachite@example.com",
            "role": "deponent"
        },
        "remote_session": {
            "title": "Example Remote Session Request",
            "case": "567-case-id-name",
            "start_date": "2025-01-28",
            "start_time": "01:30 AM",
            "time_zone": "Pacific Time (US & Canada)",
            "estimated_duration": 1.25
        },
        "session_details": {
            "additional_details": "",
            "preferred_manager": "Quartz Verbena",
            "video_provider": "chime",
            "session_type": "remote_deposition"
        },
        "postback_url": "https://www.urltosendsessioninfo.com"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(session_data))
data = response.json()
print(data)
HTTP 
POST https://prevail.ai/api/v1/sessions
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

{
    "session_request": {
        "invites": ["quartz@example.com", "obsidian@example.com"],
        "deponent": {
            "name": "Malachite Yarrow",
            "email": "malachite@example.com",
            "role": "deponent"
        },
        "remote_session": {
            "title": "Example Remote Session Request",
            "case": "567-case-id-name",
            "start_date": "2025-01-28",
            "start_time": "01:30 AM",
            "time_zone": "Pacific Time (US & Canada)",
            "estimated_duration": 1.25
        },
        "session_details": {
            "additional_details": "",
            "preferred_manager": "Quartz Verbena",
            "video_provider": "chime",
            "session_type": "remote_deposition"
        },
        "postback_url": "https://www.urltosendsessioninfo.com"
    }
}

Example Response 

{
    "requests": [
        {
            "id": 11767,
            "session_state": "initial",
            "session_url": null,
            "remote_session_id": null,
            "session_request": {
                "session_type": "remote_deposition",
                "deponent": {
                    "name": "Malachite Yarrow",
                    "email": "malachite@example.com",
                    "role": "deponent"
                },
                "invites": [
                    "quartz@example.com",  
                    "obsidian@example.com"
                ]
            },
            "remote_session": {
                "title": "Example Remote Session Request",
                "case": "567-case-id-name",
                "start_date": "2025-01-28",
                "start_time": "01:30 AM",
                "time_zone": "Pacific Time (US & Canada)",
                "estimated_duration": 1.25
            },
            "session_details": {
                "language": "en-US",
                "preferred_manager": "Quartz Verbena",
                "video_provider": "chime",
                "session_type": "remote_deposition"
            },
            "notice": null,
            "cancellation_requested": null
        }
    ]
}

Configure a Scheduled Session Webhook

Receive Session details on demand as your Session is scheduled by configuring a webhook. To configure a webhook, specify a postback_url in the Session request. Once the Scheduling Team confirms the request and schedules the Session, Prevail sends a JWT-encoded payload to the supplied webhook URL. Decode the payload using your Organization’s API key as the secret. See the postback_url for payload structure.

Postback URL Example

Once the Prevail Scheduling Team confirms your Session, your webhook endpoint receives a POST request with the payload. Use your Organization’s API key to verify the JWT signature and decode the payload. For more information about JWTs, visit https://jwt.io.

{
  "jwt_payload": "JWT_ENCODED_STRING"
}
        
{
    "requests": [
        {
            "id": 11767,
            "session_state": "scheduled",
            "session_url": "https://prevail.ai/sessions/567-case-id-name/join",
            "remote_session_id": "83b21fa4-c039-45ab-9d4a-3578bd921165",
            "session_request": {
                "session_type": "remote_deposition",
                "deponent": {
                    "name": "Malachite Yarrow",
                    "email": "malachite@example.com",
                    "role": "deponent"
                },
                "invites": [
                    "quartz@example.com",  
                    "obsidian@example.com"
                ]
            },
            "remote_session": {
                "title": "Example Remote Session Request",
                "case": "567-case-id-name",
                "start_date": "2025-01-28",
                "start_time": "01:30 AM",
                "time_zone": "Pacific Time (US & Canada)",
                "estimated_duration": 1.25
            },
            "session_details": {
                "language": "en-US",
                "preferred_manager": "Quartz Verbena",
                "video_provider": "chime",
                "session_type": "remote_deposition"
            },
            "notice": null,
            "cancelation_requested": null
        }
    ]
}

View All Session Requests

GET https://prevail.ai/api/v1/session_requests

Retrieves a list of Session requests. You can filter session_requests by passing the query string parameters start_time and end_time in epoch. When you initially create a Session Request, the session_state assigned the value initial. Once the Prevail Scheduling Team schedules the Session, session_state changes to scheduled, and the session_url is populated with a link to join the Session.

Query Parameters

start_time string optional
Filters Session requests that start after the specified date and time in EPOCH format (e.g., 1705732260).
end_time string optional
Filters Session requests that end before the specified date and time in EPOCH format (e.g., 1738011600).

Authorization

Bearer Token {{jwt_signed}}

Used to authenticate the request. Replace with your access token.

Headers

Accept application/json

Specifies the expected format of the response body.

Example Request

cURL 
curl -X GET "https://prevail.ai/api/v1/session_requests?start_time=1705732260&end_time=1738011600" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
JavaScript 
// List sessions using fetch API
const startTime = 1705732260;
const endTime = 1738011600;

const response = await fetch(
  `https://prevail.ai/api/v1/session_requests?start_time=${startTime}&end_time=${endTime}`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Accept': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data);
Python 
import requests

url = "https://prevail.ai/api/v1/session_requests"
params = {
    "start_time": 1705732260,
    "end_time": 1738011600
}
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)
HTTP 
GET https://prevail.ai/api/v1/session_requests?start_time=1705732260&end_time=1738011600
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response 

{
    "pagy": {
        "page": 1,
        "items": 2,
        "count": 2,
        "pages": 1
    },
    "requests": [
        {
            "id": 16,
            "session_state": "initial",
            "session_url": null,
            "remote_session_id": null,
            "session_request": {
                "session_type": "remote_deposition",
                "deponent": {
                    "name": "Malachite Yarrow",
                    "email": "malachite@example.com",
                    "role": "deponent"
                },
                "invites": [
                    {
                        "email": "quartz@example.com"
                    },
                    {
                        "email": "obsidian@example.com"
                    },
                    {
                        "email": "malachite@example.com"
                    }                    
                ]
            },
            "remote_session": {
                "title": "Example Remote Session",
                "case": "123-case",
                "file_number": null,
                "start_date": "2025-01-23",
                "start_time": "11:30 AM",
                "time_zone": "Pacific Time (US & Canada)",
                "estimated_duration": 1.25
            },
            "session_details": {
                "language": "en-US",
                "interpreter": "German",
                "additional_details": "Additional instructions for the deposition",
                "preferred_manager": "Quartz Verbena"
            },
            "notice": null,
            "cancelation_requested": null
        },
        {
            "id": 17,
            "session_state": "scheduled",
            "session_url": "https://staging.prevail.ai/sessions/another-example-remote-session",
            "remote_session_id": "another-example-remote-session",
            "session_request": {
                "session_type": "remote_deposition",
                "deponent": {
                    "name": "Lazuli Acacia",
                    "email": "lazuli@example.com",
                    "role": "deponent"
                },
                "invites": [
                    {
                        "email": "amber@example.com"
                    },
                    {
                        "email": "gypsum@example.com"
                    },
                    {
                        "email": "lazuli@example.com"
                    }                    
                ]
            },
            "remote_session": {
                "title": "Another Example Remote Session",
                "case": "456-case",
                "file_number": null,
                "start_date": "2025-01-24",
                "start_time": "03:30 PM",
                "time_zone": "Pacific Time (US & Canada)",
                "estimated_duration": 1.25
            },
            "session_details": {
                "language": "en-US",
                "additional_details": "Additional instructions for the deposition",
                "preferred_manager": "Amber Zinnia"
            },
            "notice": null,
            "cancelation_requested": null
        }
    ]
}

Cancel Session Requests

POST https://prevail.ai/api/v1/session_requests/[:remote_session_id]/cancel

Cancels a Session request submitted by your Organization. The Session must belong to your Organization and not yet be scheduled, which is indicated by a state of initial. Set cancel_without_email to true to prevent automatic cancellation emails from being sent to Session participants. Once cancelled, the Session state state is updated from initial to canceled.

Query Parameters

remote_session_id string required
The unique identifier for the Session you want to cancel.
  • Use the GET Sessions endpoint to retrieve a list of Sessions and their remote_session_id values.
cancel_without_email boolean optional
Determines whether cancellation email notifications are sent to participants. If assigned the value true, participants do not receive cancellation email notifications. If assigned the value false, participants receive cancellation email notifications. If omitted, the default value is false.

Authorization

Bearer Token {{jwt_signed}}

Authenticates the request. Replace with your access token.

Headers

Accept application/json

Specifies the expected format of the response body.

Example Request

cURL 
curl -X POST "https://prevail.ai/api/v1/session_requests/example_remote_session_id/cancel" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
JavaScript 
// Cancel a session request using fetch API
const sessionId = 'example_remote_session_id';

// Using an async function to use await
async function cancelSession() {
  const response = await fetch(
    `https://prevail.ai/api/v1/session_requests/${sessionId}/cancel`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    }
  );

  const data = await response.json();
  console.log(data);
}

// Call the function
cancelSession();
Python 
import requests

session_id = "example_remote_session_id"
url = f"https://prevail.ai/api/v1/session_requests/{session_id}/cancel"

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

response = requests.post(url, headers=headers)
data = response.json()
print(data)
HTTP 
POST https://prevail.ai/api/v1/session_requests/example_remote_session_id/cancel
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

Example Response 

{
  "messages": "Session successfully canceled."
}
Copyright ©2025 Prevail Legal

Last modified: May 22, 2025