Link Search Menu Expand Document

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

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:

GET https://prevail.ai/api/v1/sessions?per_page=10&page=2

Query Parameters

per_page optional
The number of items to return per page. The default value is 100, which can be adjusted to a maximum of 1000. In this example, per_page=10 returns 10 items per page.
page optional
The page number of results to return, starting at 1 for the first page. For example, page=2 returns the second page of results. If per_page=10, the second page contains items 11–20.

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 Parameter Path Type
pagy pagy object
Contains pagination details, including the current page, items per page, total item count, and total pages.
page pagy.page integer
The current page number of results to be returned. For example, setting page=2 retrieves the second page of results.
items pagy.items integer
Specifies the number of items to return per page. Use the per_page query string parameter to set a value up to a maximum of 1000. If omitted, the defaults to 100.
count pagy.count integer
The total number of items available across all pages. For example, count=21 indicates there are 21 items in the dataset.
pages pagy.pages integer
The total number of pages required to display all items in the dataset. This value is calculated as pages = ⌈count / items⌉. For example, with count=21 and items=10, the result is pages = ⌈21 / 10⌉ = 3.

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.

Error Handling

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

HTTP Error Codes
HTTP Status Description Resolution
400 Bad Request The request contains invalid parameters Check your request payload
401 Unauthorized The request is missing a valid JWT token Provide a valid token in the headers
404 Not Found The requested resource could not be found Verify the resource identifier
422 Unprocessable Entity The request payload is valid, but could not be processed due to invalid field values or constraints Ensure required fields are valid
500 Internal Server Error The server encountered an unexpected condition that prevented it from fulfilling the request Wait a few moments and retry the request. If the issue persists, contact Prevail Support

Copyright ©2025 Prevail Legal

Last modified: May 22, 2025