Link Search Menu Expand Document

Prevail API: Session Requests

Submit Session Requests

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

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

Configuring a Scheduled Session Webhook

To determine when a Session has been scheduled and to retrieve the join URL for your Session, you can retrieve a list of Session Requests via the GET /session_requests endpoint.

Alternatively, you can receive Session details on demand as your Remote Session is scheduled by configuring a webhook. You can configure a webhook by specifying a postback_url in the Session request. When the Scheduling Team confirms the request and schedules the Session, Prevail sends a JWT-encoded payload to your supplied webhook URL. The payload can be decoded using your Organization’s API key as the secret. See the postback_url for payload structure.

Request Body Parameters

View Parameters
session_request object required
The details of the Session, including participant emails, Session information, and additional settings.
invite_emails array optional
A list of participant email addresses for the Session. For example: ["john@smith.com", "jane@doe.com"].
deponent object optional
Information about the deponent or witness participant, including their name, email, and role.
name string optional
The name of the deponent or witness participant. For example: John Smith.
email string optional
The email address of the deponent or witness participant. For example: john@smith.com.
role string optional
The role of the deponent or witness participant in the Session. Valid options are deponent and witness.
remote_session object required
The details about the remote Session, including the title, case identifier, and scheduled time.
title string required
case string required
The case identifier for the Session. For example: 123-case-id-name.
start_date string required
The date the Session is scheduled to start, formatted as YYYY-MM-DD. For example: 2025-01-28.
start_time string required
The time the Session is scheduled to start, formatted in 12-hour clock with AM/PM. For example: 01:30 AM.
time_zone string required
The time zone of the Session. Accepts valid time zones formatted with GMT offsets and region descriptions. The most commonly used values are: Eastern Time (US & Canada), Central Time (US & Canada), Mountain Time (US & Canada), Pacific Time (US & Canada), Alaska, Hawaii. For a comprehensive list of all time zones, refer to the IANA Time Zone Database.
session_details object optional
Additional details about the Session, including languages spoken or understood during the Session. For example: English, German.
languages array optional
A list of languages spoken or understood during the Session. Include English and one or more languages from the interpreter parameter if the Session requires a language interpreter. Default value is English.
interpreter string optional
The language interpreter required for the Session. Accepted values include: Afrikaans, Arabic, Gulf, Arabic, Modern Standard, Chinese, Mandarin (Mainland China), Chinese, Mandarin (Taiwan), Danish, Dutch, English, Australian, English, British, English, Indian, English, Irish, English, New Zealand, English, Scottish, English, South African, English, US, English, Welsh, French, French, Canadian, Farsi, German, German, Swiss, Hebrew, Hindi, Indian, Indonesian, Italian, Japanese, Korean, Malay, Portuguese, Portuguese, Brazilian, Russian, Spanish, Spanish, US, Tamil, Telugu, Thai, Turkish, Other.
additional_details string optional
Additional information or comments about the Session.
preferred_manager string optional
The name of the preferred manager for the Session.
video_provider string optional
The Session backend provider. Accepted value is chime. Default value is chime.
session_type string optional
The Session type. Accepted values: remote_deposition, remote_call, webinar. Default value is remote_deposition.
postback_url string required
The URL where Session information should be sent after creation. For example: https://example.com/webhook.

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 format of the response body.

Example Request

{
    "session_request": {
        "invite_emails": ["john@smith.com", "jane@doe.com"],
        "deponent": {
            "name": "John Smith",
            "email": "john@smith.com",
            "role": "deponent"
        },
        "remote_session": {
            "title": "requested session",
            "case": "567-case-id-name",
            "start_date": "2025-01-28",
            "start_time": "01:30 AM",
            "time_zone": "Pacific Time (US & Canada)"
        },
        "session_details": {
            "additional_details": "",
            "preferred_manager": "Ash Smith",
            "video_provider": "chime",
            "session_type": "remote_deposition"
        },
        "postback_url": "https://www.urltosendsessioninfo.com"
    }
}
        
Example Response

{
    "requests": [
        {
            "id": 11767,
            "session_state": "initial", // Request submitted to Prevail Staff for review
            "session_url": null,
            "remote_session_id": null,
            "session_request": {
                "session_type": "remote_deposition",
                "deponent": {
                    "name": "John Smith",
                    "email": "john@smith.com",
                    "role": "deponent"
                },
                "invite_emails": [
                    "john@smith.com",
                    "jane@doe.com"
                ]
            },
            "remote_session": {
                "title": "requested session",
                "case": "567-case-id-name",
                "start_date": "2025-01-28",
                "start_time": "01:30 AM",
                "time_zone": "Pacific Time (US & Canada)"
            },
            "session_details": {
                "language": "en-US",
                "preferred_manager": "Ash Smith",
                "video_provider": "chime",
                "session_type": "remote_deposition"
            },
            "notice": null,
            "cancelation_requested": null
        }
    ]
}
        

Postback URL Example

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

Example Webhook Payload

// Webhook payload :
{
  "jwt_payload": "JWT_ENCODED_STRING"
}

// Decoded payload contains:
{
  "sessions": [
    {
      "remote_session_id": "example-remote-session-id",
      "title": "Example Remote Session",
      "start_date": "2025-01-28",
      "start_time": "01:30 AM",
      "time_zone": "Pacific Time (US & Canada)",
      "state": "ready",
      "estimated_duration": 4.0,
      "transcript_status": "in_progress",
      "invite_emails": [
        "john@smith.com",
        "jane@doe.com"
      ]
    }
  ]
}
        

View All Session Requests

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

Retrieves a list of all Session Requests. You can filter session_requests by passing the query string parameters start_time and end_time in epoch. When a Session Request is created initially, the session_state is set to initial. Once the Prevail Scheduling Team schedules the Session, session_state will change to scheduled, and the session_url will be 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

Content-Type application/json

Specifies the format of the request body.

Accept application/json

Specifies the format of the response body.

Example Request

GET https://prevail.ai/api/v1/session_requests?start_time=1705732260&end_time=1738011600
        
Example Response

{
    "pagy": {
        "page": 1,
        "items": 2,
        "count": 2,
        "pages": 1
    },
    "requests": [
        {
            "id": 16,
            "session_state": "initial",
            "session_url": null,
            "session_request": {
                "session_type": "deposition",
                "deponent": {
                    "name": "John Smith",
                    "role": "deponent",
                    "email": "john@smith.com"
                },
                "participants": null
            },
            "remote_session": {
                "title": "David v Goliath",
                "case": "123-case",
                "file_number": null,
                "start_date": "2025-01-23",
                "start_time": "01:30 AM",
                "time_zone": "EST"
            },
            "session_details": {
                "language": "en-US",
                "interpreter": "German",
                "additional_details": "Other instructions for the depo",
                "preferred_manager": "Ashley Smith"
            },
            "notice": null,
            "cancelation_requested": null
        },
        {
            "id": 14,
            "session_state": "initial",
            "session_url": null,
            "session_request": {
                "session_type": "deposition",
                "deponent": {
                    "name": "John Smith",
                    "role": "deponent",
                    "email": "john@smith.com"
                },
                "participants": null
            },
            "remote_session": {
                "title": "David v Goliath",
                "case": "123-case",
                "file_number": null,
                "start_date": "2025-01-23",
                "start_time": "01:30 AM",
                "time_zone": "EST"
            },
            "session_details": {
                "language": "en-US",
                "interpreter": "German",
                "additional_details": "Other instructions for the depo",
                "preferred_manager": "Ashley Smith"
            },
            "notice": null,
            "cancelation_requested": null
        }
    ]
}
        

Copyright ©2025 Prevail Legal

Last modified: January 24, 2025