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
- Schedule Sessions (Self-Service)
- View Scheduled Sessions
- Edit Scheduled Sessions
- Cancel Scheduled Sessions
- Submit Session Requests
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:
- 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 into 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 will be used as the slug parameter in your JWT payload.
- Log into 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 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 yourcompany_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.
- Replace
prevail_api_key
with the actual value - Replace
company_id
with the actual value
// 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:
Query Parameters
100
, and this can be adjusted up to a maximum of 1000
. In this example, per_page=10
returns 10 items per page. 1
for the first page. In this example, page=2
retrieves the second page of results, containing items 11–20 when per_page=10
.
{
"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
page=2
retrieves the second page of results. 100
, but you can use the per_page
query string parameter to set a value up to a maximum of 1000
. count=21
indicates there are 21 items in the dataset. 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 | 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. |