Symtrain Public APIs - Version 2 (Recommended)
This is the documentation for Symtrain Public APIs Version 2 - our latest and recommended API version.
Overview
The Version 2 API provides enhanced access to:
- Reports: Improved APIs that allow you to fetch various performance and result-based reports with additional data points.
- Access API: Enhanced endpoints to generate deep links for simulations, manage simulation assignments, and retrieve comprehensive simulation data.
Base URL
Code
What's New in V2?
Version 2 includes enhancements and additional features compared to v1:
- Improved data structures for better integration
- Additional endpoints for simulation assignment management
- Enhanced error handling and response formats
- More detailed simulation data retrieval
Authentication
All API endpoints require authentication using a Bearer token in the Authorization header:
Code
Getting Started
- Obtain your API Key from the Symtrain support team
- Review the API Reference v2 for detailed endpoint documentation
- Start making requests to the API endpoints
Key Features
Reports
All report endpoints support enhanced data structures and additional filtering options in v2.
POST /v2/report/syms-result
Retrieve detailed Sym Result Reports with enhanced system-level performance data and metrics.
POST /v2/report/user-results
Generate an enhanced User Results Report with additional performance metrics.
POST /v2/report/training-plan-result
Obtain a comprehensive Training Plan Results Report with improved data points.
POST /v2/report/modules-results
Get a Module Results Report with enhanced module performance data.
POST /v2/report/syms
Retrieve the Sym Report with expanded insights and metrics.
POST /v2/report/users
Generate a Users Report with additional user analytics.
POST /v2/report/teams-result
Retrieve a Team Results Report with enhanced team performance metrics.
Common Request Body for Reports:
startDate(required) - Start date (format: YYYY-MM-DD)endDate(required) - End date (format: YYYY-MM-DD)- Date range must be within 3 months (180 days)
Access API
Enhanced endpoints with new features for simulation management and user access.
POST /v2/access-api/simulation/deep-links
Generate simulation deep-links for direct access to specific simulations.
Request Body:
organizationId(required) - Organization identifieruserId(required) - User identifiersimulationId(required) - Simulation identifier
Returns: Deep-link URL for simulation access
POST /v2/access-api/simulation/completion-data
Retrieve Completion Data for all simulation executions (started, interrupted, and completed).
Important: The response includes all execution attempts. To distinguish completion status:
- Completed: Both
completedAtandcompletionTimehave values - Incomplete: Both
completedAtandcompletionTimearenull
Request Body:
organizationId(required) - Organization identifieruserId(required) - User identifiersimulationId(required) - Simulation identifier
🆕 POST /v2/access-api/simulation/library
New in v2: Retrieve all simulations available in the SymTrain library for a specific organization.
Request Body:
organizationId(required) - Organization identifieruserId(required) - User identifiertags(optional) - Array of tags for filteringsearchTerm(optional) - Search term for filteringpage(optional) - Page number for paginationpageSize(optional) - Number of items per page
🆕 POST /v2/access-api/simulation/assignment
New in v2: Assign or unassign a specific simulation to/from a user.
Request Body:
organizationId(required) - Organization identifieruserId(required) - User identifiersimulationId(required) - Simulation identifierassign(required) - Boolean (true to assign, false to unassign)
Returns: Simulation details with deep-link URL (when assign=true) or success status (when assign=false)
🆕 POST /v2/access-api/user/token
New in v2: Generate a short-lived access token (valid for 1 hour) for user impersonation.
Request Body:
organizationId(required) - Organization identifieruserId(required) - User identifier
Usage Example: Add the token as a query parameter to simulation deep-links:
Code
🆕 POST /v2/access-api/user/bulk-import
New in v2: Bulk import users by uploading a CSV file.
Request Format:
- Content-Type:
multipart/form-data - Maximum 750 records per file
- Returns
taskIdfor tracking import status
Form Data:
organizationId(required) - Organization identifierfile(required) - CSV file with user data
CSV File Format:
The CSV file must include the following columns:
| Column | Required | Description | Example |
|---|---|---|---|
| firstName | Yes | User's first name | John |
| lastName | Yes | User's last name | Doe |
| username | Yes | Username (must match email) | [email protected] |
| Yes | Email address (must match username) | [email protected] | |
| role | Yes | User role (currently only "trainee" supported) | trainee |
| teamName | No | Team assignment (optional) | Sales Team |
| status | Yes | User status | ACTIVE |
| action | Yes | Action to perform | Add |
Valid Values:
- role:
trainee(only value currently supported) - status:
ACTIVEorINACTIVE - action:
AddorUpdate
Example CSV File:
Code
Validation Rules:
- ✅ Maximum 750 records per file
- ✅ Email must match username exactly
- ✅ Only "trainee" role is supported
- ✅ File must be in CSV format with proper headers
- ✅ taskId is generated only if at least one valid user exists
Error Handling:
If any row has validation errors, the API returns:
- List of field errors for each invalid row
- Row number for easy identification
- Valid user count and invalid user count
- taskId (if at least one valid user exists)
See the API Reference for complete request/response schemas.
🆕 POST /v2/access-api/user/bulk-import/status
New in v2: Check the status of a bulk import task.
Request Body:
organizationId(required) - Organization identifiertaskId(required) - Task ID from bulk import response
Status Flow:
- Success: SCHEDULED → STARTED → COMPLETED
- Error: SCHEDULED → STARTED → FAILED
🆕 POST /v2/access-api/user/create
New in v2: Create a new trainee user or retrieve existing user data.
Request Body:
organizationId(required) - Organization identifieremail(required) - User email (must match username)username(required) - Username (must match email)firstName(optional) - First namelastName(optional) - Last name- Additional user fields as needed
Note: Only supports creating users with the 'trainee' role
Rate Limiting
- 100 requests per 5-minute window per IP address
429 Too Many Requestsresponse when limit exceeded
Common Error Codes
| Code | Description |
|---|---|
| 400 | Bad Request - Invalid data or missing parameters |
| 401 | Unauthorized - Invalid or missing API key |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource not found |
| 500 | Internal Server Error - Server-side issue |
Migration from V1
If you're currently using API v1, we recommend migrating to v2 to take advantage of:
- New features and endpoints
- Improved performance
- Better error handling
- Enhanced data structures
Review the API Reference v2 to see the complete list of available endpoints.
Support
For questions or issues, contact our support team at: [email protected]
📖 Full API Reference
For complete interactive API documentation with all endpoints, request/response schemas, and the ability to test endpoints:
View Complete API v2 Reference →