Prevail API: Edit Sessions

Edit Sessions (Self-Service)

Edit Sessions (Self-Service)

PATCH https://prevail.ai/api/v1/sessions/[:remote_session_id]

Makes changes to a Session previously created by your Organization. The Session must belong to the Organization attempting to edit it and be in a state of scheduled or ready. Your Organization must have Self-Service enabled to use this request to directly schedule Sessions. Only Prevail Staff can enable Self-Service for your Organization.

To update any of start_date, start_time, or time_zone, all three options must be included.

Query Parameters

remote_session_id string required

The unique identifier for the Session you want to edit.

You can retrieve the remote_session_id by using the GET Sessions endpoint, which returns a list of Sessions and their IDs.

Request Body Parameters

View Parameters

remote_session object required

Details about the remote Session, including the title, case identifier, and scheduled time.

start_time string optional*

The time the Session is scheduled to start, formatted in 12-hour clock as hh:mm AM/PM. For example: 01:30 AM.

start_date string optional*

The date the Session is scheduled to start, formatted as YYYY-MM-DD. For example: 2025-01-28.

time_zone string optional*

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.

title string optional

The Session title.

invites array optional

A list of participant email addresses for the Session, including both participants and Hosts. Any email added to the invites array without an access_level will be included as a regular participant and will not have Host permissions. To designate a Host, you must include the access_level parameter set to host. If a Host is specified, the email must belong to a registered Prevail Member; otherwise, they will be added as a regular participant without Host permissions. For example:

[{ "email": "azurite@example.com", "access_level": "host" }, { "email": "quartz@example.com" }, { "email": "obsidian@example.com" }, { "email": "amethyst@example.com" }]

. Participants added to the list will automatically receive Session notification emails. Once participants are invited, they cannot be removed from the Session. If you need to remove one or more participants, you can cancel the Session using the PATCH Cancel Session API request and schedule a new Session with the correct participants.

email string optional

The email address of the Session participant. If access_level is not specified, the participant will be included as a regular participant without Host permissions. To assign Host permissions, the access_level parameter must be set to host. A participant assigned Host must have an email address associated with a registered Prevail Member account. Otherwise, they will be included as a regular participant without Host permissions.

access_level string optional

The role of the Session participant associated with the email. Use this parameter to assign Host permissions to the participant. If omitted, the participant will be included as a regular participant without Host permissions. Accepted values: host. For example: [{ "email": "azurite@example.com", "access_level": "host" }].

estimated_duration number optional

The updated estimated duration of the Session in hours. Accepts decimal values. For example: 2.5 for 2 hours and 30 minutes.

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


PATCH https://prevail.ai/api/v1/sessions/example-remote-session-id

{
    "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json"
    },
   "remote_session": {
        "title": "Example Remote Session Edited", // Edit Session title
        "start_time": "02:30 PM", // Edit start date and time
        "start_date": "2025-01-30", // Edit start date and time
        "time_zone": "Pacific Time (US & Canada)", // Edit start date and time
        "invites": ["amethyst@example.com"] // Add a participant email
    }
}

Example Response


{
    "sessions": [
        {
            "remote_session_id": "example-remote-session-id",  // remote_session_id does not change
            "title": "Example Remote Session Edited",  // Session title updated
            "start_date": "2025-01-30", // start_date updated
            "start_time": "02:30 PM", // start_time updated
            "time_zone": "Pacific Time (US & Canada)", 
            "state": "ready",
            "estimated_duration": 3.5,
            "transcript_status": "in_progress",
            "invites": [
                "quartz@example.com",
                "obsidian@example.com",
                "amethyst@example.com" // Participant email added to Session
            ],
            "provider_specific_details": { // provider_specific_details does not change
                "meeting_id": 97969731904,
                "password": "ysitdagyst",
                "provider_join_url": "https://zoom.us/j/97969731904?pwd=MhujrdD4UXWIeubEbPJhDbhKs1VT0P.1",
                "prevail_join_url": "https://staging.prevail.ai/sessions/example-remote-session/zoom_meeting"
            }
        }
    ]
}