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
- 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:
- Authentication: A JSON Web Token (JWT) signed with your organization's API key.
- API Key from your Organization's settings.
- Company ID from your Organization's settings.
Retrieve Your Organization’s prevail_api_key
- Log in to your Prevail account.
- On the Navigation menu, click Organizations.
- Click the Organization name.
- 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.
- Log in to your Prevail account.
- On the Navigation menu, click Organizations.
- Click the Organization name.
- 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 yourcompany_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
100
, which can be adjusted to a maximum of 1000
. In this example, per_page=10
returns 10 items per page. 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 | 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 |