Prevail API User Guide

Use Prevail’s API to perform scheduling tasks and retrieve Organization and Session information. Our API supports the standard HTTP methods GET, POST, and PATCH.

• Core Features
• Requirements
  • Retrieve Your Organization’s prevail_api_key
  • Identify Your Organization’s company_id
• Authentication
  • Generate a JSON Web Token (Node.js)
  • Include JWT in Your API Request
• Pagination
  • Query Parameters
    • Example Response
    • Response Fields
• Field Reference Tables
• Error Handling

Core Features

• Schedule Sessions (Self-Service)
• View Scheduled Sessions
• Edit Scheduled Sessions
• Cancel Scheduled Sessions
• Submit Session Requests

Requirements

The Prevail API follows RESTful principles with predictable URLs and a consistent structure for responses and errors. To use the API, you need the following:

1. Authentication: A JSON Web Token (JWT) signed with your organization's API key.
2. API Key from your Organization's settings.
3. Company ID from your Organization's settings.

Retrieve Your Organization’s prevail_api_key

1. Log in to your Prevail account.
2. On the Navigation menu, click Organizations.
3. Click the Organization name.
4. In the Credentials section, in the Active API Key box, click Copy.

Identify Your Organization’s company_id

Locate your Company ID. This value is used as the slug parameter in your JWT payload.

1. Log in to your Prevail account.
2. On the Navigation menu, click Organizations.
3. Click the Organization name.
4. In the Credentials section, locate the Company ID.

Authentication

The Prevail API authenticates requests using JWTs (JSON Web Tokens). A JSON Web Token (JWT) securely transfers information between your application and the API in a compact, URL-safe format. To learn more about JWTs and their use, visit jwt.io.

We provide a Node.js script in our Postman collection that runs automatically if your company_id and prevail_api_key are supplied as environment variables.

• Replace prevail_api_key with your Organization’s Active API Key
• Replace company_id with your Organization’s Company ID

The payload contains parameters sent to the Prevail API. The JWT payload must include both an exp (expiration time in epoch seconds) and a slug (your organization’s company_id), which are required to validate and authenticate your request.

• exp is the epoch time in seconds and defines when the token expires.
• slug is your company_id and identifies your Organization in API requests.

For additional security, include parameters in the JWT payload instead of passing them through the query string or POST body.

Generate a JSON Web Token (Node.js)

To generate the token, you’ll need the jsonwebtoken package (npm install jsonwebtoken) and Node.js version 12 or later.

const jwt = require('jsonwebtoken');

const token = jwt.sign(
  { exp: Math.floor(Date.now()/1000) + 3600, slug: 'company_id' },
  'prevail_api_key',
  { algorithm: 'HS256' }
);
console.log(token);

Include JWT in Your API Request

Once your JWT is generated, include it in the API request authorization header, query parameter, or POST body.

• Authorization Header: Authorization: Bearer [your_jwt_token]
• Query String Parameter: ?jwt_payload=[signed_jwt]
• POST Body: Include jwt_payload in the request body along with other parameters

Pagination

The Prevail API uses pagination to improve performance when retrieving Sessions and related data. For details, see the GET Sessions endpoint. Responses include pagination metadata in a JSON object alongside the returned data.

To traverse the pages, include the page query string parameter in your request. To change the number of items returned per page, include the per_page query string parameter. The default is 100 items per page, and the maximum is 1000.

Example:

Query Parameters

Example Response

{
    "pagy": {
        "page": 2,
        "items": 10,
        "count": 21,
        "pages": 3
    },
    "sessions": [
        { "remote_session_id": "..." },
        { "remote_session_id": "..." },
        { "remote_session_id": "..." },
        { "remote_session_id": "..." },
        { "remote_session_id": "..." },
        { "remote_session_id": "..." },
        { "remote_session_id": "..." },
        { "remote_session_id": "..." },
        { "remote_session_id": "..." },
        { "remote_session_id": "..." }
    ]
}
        

Response Fields

Field Reference Tables

Prevail provides field reference tables for both request bodies and response payloads. These tables clarify the structure of nested parameters, identify required fields, and include detailed descriptions for each item.

• View Request Fields
• View Response Fields

Error Handling

The Prevail API uses standard HTTP status codes to indicate the success or failure of requests.