Link Search Menu Expand Document

Prevail API: Schedule Sessions

Schedule Sessions (Self-Service)

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

Creates a new scheduled Session. Your Organization must have Self-Service enabled to use this endpoint to directly schedule Sessions. For Organizations without Self-Service, submit a Session request. All participants listed in the invites array receive email notifications containing Session details and join instructions.

For Zoom Meeting backend provider Sessions, all Session information is contained in the provider_specific_details response field object, including the meeting_id, password, prevail_join_url, and provider_join_url to access the Session.

Authorization

Bearer Token {{jwt_signed}}

Authenticates 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

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",
            "case": "123-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": "Quartz Verbena",
            "video_provider": "zoom_meeting",
            "session_type": "remote_deposition"
        }
    }
}'
JavaScript 
// Create a Zoom 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",
      case: "123-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: "Quartz Verbena",
      video_provider: "zoom_meeting",
      session_type: "remote_deposition"
    }
  }
};

// Using an async function to use await
async function createZoomSession() {
  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);
}

// Call the function
createZoomSession();
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",
            "case": "123-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": "Quartz Verbena",
            "video_provider": "zoom_meeting",
            "session_type": "remote_deposition"
        }
    }
}

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",
            "case": "123-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": "Quartz Verbena",
            "video_provider": "zoom_meeting",
            "session_type": "remote_deposition"
        }
    }
}

Example Response 

{
    "requests": [
        {
            "id": 11760,
            "session_state": "scheduled",
            "session_url": "https://staging.prevail.ai/sessions/example-remote-session-id",
            "remote_session_id": "example-remote-session-id",
            "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-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": "zoom_meeting",
                "session_type": "remote_deposition"
            },
            "notice": null,
            "cancelation_requested": null,
            "provider_specific_details": {
                "meeting_id": 95317175962,
                "password": "awt4zzi7jv",
                "provider_join_url": "https://zoom.us/j/95317175962?pwd=E0Vmti19iYagOKzfZH08qJNKxlb5SG.1",
                "prevail_join_url": "https://staging.prevail.ai/sessions/example-remote-session/zoom_meeting"
            }
        }
    ]
}
Field Parameter Path Type
meeting_id requests[].provider_specific_details.meeting_id integer
The unique meeting ID for the Session, specific to the selected video_provider. Example: 92583913564.
password requests[].provider_specific_details.password string
The password required to join the meeting through the selected video_provider. Example: 4c5siwtlvu.
provider_join_url requests[].provider_specific_details.provider_join_url string
The URL for participants to join the meeting directly through the selected video_provider. Example: https://zoom.us/j/92583913564?...etc.
prevail_join_url requests[].provider_specific_details.prevail_join_url string
The URL for participants to join the meeting through the Prevail Sessions app instead of the selected video_provider. Example: https://prevail.ai/sessions/example-remote-session/zoom_meeting.

Assign Session Hosts

To assign a Host to a Session, include their email address in the invites array within the session_requests object, and set the access_level to host. The email address of the assigned Host must match the email address of a registered Prevail Member. If the email is not associated with a registered Member, the participant is automatically assigned the participant role and will not have Host permissions for the Session.

The participant role is assigned by default to each email, unless the access_level parameter is explicitly assigned the value host.

Example Request Assigning Hosts

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": [
            {
                "email": "azurite@example.com",
                "access_level": "host"
            },
            {
                "email": "selenite@example.com",
                "access_level": "host"
            },            
            {
                "email": "quartz@example.com"
            },
            {
                "email": "obsidian@example.com"
            },
            {
                "email": "amethyst@example.com"
            }                                    
        ],
        "deponent": {
            "name": "Malachite Yarrow",
            "email": "malachite@example.com",
            "role": "deponent"
        },
        "remote_session": {
            "title": "Example Remote Session",
            "case": "123-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": {
            "languages": "",
            "interpreter": "",
            "additional_details": "",
            "preferred_manager": "Azurite Oleander",
            "video_provider": "",
            "session_type": "remote_deposition"
        }
    }
}'
JavaScript 
// Create a session using fetch API
const sessionData = {
  session_request: {
    invites: [
      {
        email: "azurite@example.com",
        access_level: "host"
      },
      {
        email: "selenite@example.com",
        access_level: "host"
      },
      {
        email: "quartz@example.com"
      },
      {
        email: "obsidian@example.com"
      },
      {
        email: "amethyst@example.com"
      }
    ],
    deponent: {
      name: "Malachite Yarrow",
      email: "malachite@example.com",
      role: "deponent"
    },
    remote_session: {
      title: "Example Remote Session",
      case: "123-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: {
      languages: "",
      interpreter: "",
      additional_details: "",
      preferred_manager: "Azurite Oleander",
      video_provider: "",
      session_type: "remote_deposition"
    }
  }
};

// Using an async function to use await
async function createSession() {
  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);
}

// Call the function
createSession();
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": [
            {
                "email": "azurite@example.com",
                "access_level": "host"
            },
            {
                "email": "selenite@example.com",
                "access_level": "host"
            },
            {
                "email": "quartz@example.com"
            },
            {
                "email": "obsidian@example.com"
            },
            {
                "email": "amethyst@example.com"
            }
        ],
        "deponent": {
            "name": "Malachite Yarrow",
            "email": "malachite@example.com",
            "role": "deponent"
        },
        "remote_session": {
            "title": "Example Remote Session",
            "case": "123-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": {
            "languages": "",
            "interpreter": "",
            "additional_details": "",
            "preferred_manager": "Azurite Oleander",
            "video_provider": "",
            "session_type": "remote_deposition"
        }
    }
}

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": [
            {
                "email": "azurite@example.com",
                "access_level": "host"
            },
            {
                "email": "selenite@example.com",
                "access_level": "host"
            },            
            {
                "email": "quartz@example.com"
            },
            {
                "email": "obsidian@example.com"
            },
            {
                "email": "amethyst@example.com"
            }                                    
        ],
        "deponent": {
            "name": "Malachite Yarrow",
            "email": "malachite@example.com",
            "role": "deponent"
        },
        "remote_session": {
            "title": "Example Remote Session",
            "case": "123-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": {
            "languages": "",
            "interpreter": "",
            "additional_details": "",
            "preferred_manager": "Azurite Oleander",
            "video_provider": "",
            "session_type": "remote_deposition"
        }
    }
}

Specify the Session URL path (remote_session_id)

The remote_session_id request parameter allows you to define a unique identifier for the Session URL. If provided, the remote_session_id must be unique across all scheduled Sessions; otherwise an error is returned. Any spaces in the remote_session_id are converted into dashes, and all capital letters are converted to lowercase. If omitted, the title parameter is automatically formatted into the remote_session_id for the Session. For a complete reference on URL formatting rules, see RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax.

Once a Session is scheduled, the remote_session_id cannot be changed. To use a different remote_session_id, cancel the Session and schedule a new Session using the desired remote_session_id.

Example Request Specifying remote_session_id

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",
            "remote_session_id": "Custom Unique Session URL",
            "case": "123-case-id-name",
            "start_date": "2025-01-30",
            "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": "zoom_meeting",
            "session_type": "remote_deposition"
        }
    }
}'
JavaScript 
// Create a session with Zoom 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",
      remote_session_id: "Custom Unique Session URL",
      case: "123-case-id-name",
      start_date: "2025-01-30",
      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: "zoom_meeting",
      session_type: "remote_deposition"
    }
  }
};

// Using an async function to use await
async function createZoomSession() {
  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);
}

// Call the function
createZoomSession();
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",
            "remote_session_id": "Custom Unique Session URL",
            "case": "123-case-id-name",
            "start_date": "2025-01-30",
            "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": "zoom_meeting",
            "session_type": "remote_deposition"
        }
    }
}

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",
            "remote_session_id": "Custom Unique Session URL",
            "case": "123-case-id-name",
            "start_date": "2025-01-30",
            "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": "zoom_meeting",
            "session_type": "remote_deposition"
        }
    }
}
Copyright ©2025 Prevail Legal

Last modified: May 22, 2025