Link Search Menu Expand Document

Prevail API User Guide

The Prevail API allows you to interact with Prevail’s core features, including retrieving Organization and Session information and performing scheduling tasks. Designed for simplicity, our API supports the standard HTTP methods GET, POST, and PATCH.

Core Features

Requirements

The Prevail API adheres to RESTful principles, ensuring predictable resource URLs and a consistent structure for responses and errors. Before using the API, you will 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 into 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 will be used as the slug parameter in your JWT payload.

  1. Log into 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 uses JWTs (JSON Web Tokens) to authenticate all requests. The following section provides an example script of how to generate a JWT token in Javacript. Additionally, this script is included in our Postman collection and will run automatically if your company ID and Prevail API key are supplied as environment variables.

The payload data is used to send in parameters to the Prevail API. For the API to accept the token, it is required that you pass in both the exp and the slug parameters.

  • exp is the epoch time in seconds.
  • slug is your company_id used to identify your Organization credentials.

For additional security, parameters can be passed in the JWT payload instead of the query string or POST body.

Generate a JSON Web Token

A JSON Web Token (JWT) is a compact, URL-safe way to securely transfer information between your application and the API. To learn more about JWTs and their use, visit jwt.io.

javascript

// This script demonstrates how to generate a JWT for scheduling sessions via the API.
// It uses the 'crypto' module, which is built into Node.js, and is intended for server-to-server communication.
// Note: This example will NOT work in Postman or browser environments.
// Ensure your server securely stores the API key to prevent unauthorized access.

const crypto = require('crypto');

// Step 1: Define your secret key and payload
const secretKey = 'your_api_key'; // Replace with your actual API key
const payload = {
  exp: Math.floor(Date.now() / 1000) + 3600, // Token expires in 1 hour
  slug: 'your_company_id', // Replace with your company_id
};

// Step 2: Define the header
const header = {
  alg: 'HS256',
  typ: 'JWT',
};

// Step 3: Base64 URL Encode the header and payload
function base64UrlEncode(obj) {
  const json = JSON.stringify(obj);
  const buffer = Buffer.from(json);
  return buffer.toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
}

const encodedHeader = base64UrlEncode(header);
const encodedPayload = base64UrlEncode(payload);

// Step 4: Create the signature
const dataToSign = `${encodedHeader}.${encodedPayload}`;
const signature = crypto
  .createHmac('sha256', secretKey)
  .update(dataToSign)
  .digest('base64')
  .replace(/=+$/, '')
  .replace(/\+/g, '-')
  .replace(/\//g, '_');

// Step 5: Assemble the JWT
const jwt = `${encodedHeader}.${encodedPayload}.${signature}`;

console.log('Generated JWT:', jwt);
        

Include JWT in Your API Request

Once your JWT is generated, you can include it in one of the following: 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 as part of the request payload

Pagination

The API uses pagination to enhance performance and efficiency when handling large datasets. Pagination is applied to operations that could return a significant number of items. When you request a paginated resource, the response wraps the returned data in a JSON object that includes metadata about the pagination.

To traverse the pages, include the page query string parameter in your request. If you wish to return more or less than 100 items per page, you can include the per_page query string parameter with an upper limit of 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, and this can be adjusted up 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. In this example, page=2 retrieves the second page of results, containing items 11–20 when per_page=10.
Example Response

{
    "pagy": {
        "page": 2,
        "items": 10,
        "count": 21,
        "pages": 3
    },
    "sessions": [
        { /* session data */ },
        { /* session data */ },
        { /* session data */ }, 
        { /* session data */ },
        { /* session data */ },
        { /* session data */ },               
        { /* session data */ }
        { /* session data */ },
        { /* session data */ },
        { /* session data */ },        
    ]
}
        

Response Fields

View Response Fields
pagy object
Contains pagination details, including the current page, items per page, total item count, and total pages.
page integer
The current page number of results to be returned. For example, setting page=2 retrieves the second page of results.
items integer
The number of items to be returned per page. The default is 100, but you can use the per_page query string parameter to set a value up to a maximum of 1000.
count integer
The total number of items available across all pages. For example, count=21 indicates there are 21 items in the dataset.
pages integer
The total number of pages required to display all items. This value is calculated as pages = ⌈ count / items ⌉. For example, with count=21 and items=10, the result is pages = ⌈ 21 / 10 ⌉ = 3.

Error Handling

The Prevail API uses standard HTTP status codes to indicate 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 headers.
404 Not Found The requested resource could not be found. Verify the resource identifier.
422 Unprocessable Entity The request payload is correct but cannot be processed. Ensure required fields are valid.
500 Internal Server Error A server error occurred. Retry the request or contact support.

Copyright ©2025 Prevail Legal

Last modified: January 24, 2025