Prevail API: Session Requests
Submit 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
["john@smith.com", "jane@doe.com"]
. John Smith
. john@smith.com
. deponent
and witness
. 123-case-id-name
. YYYY-MM-DD
. For example: 2025-01-28
. 01:30 AM
. 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. languages
spoken or understood during the Session. For example: English
, German
. English
and one or more languages from the interpreter parameter if the Session requires a language interpreter. Default value is English
. 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
. remote_deposition
, remote_call
, webinar
. Default value is remote_deposition
. 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.
{
"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"
}
}
{
"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.
// 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
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
1705732260
). 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.
GET https://prevail.ai/api/v1/session_requests?start_time=1705732260&end_time=1738011600
{
"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
}
]
}