Documentation

Migration Guide - v1 to v2

Copy page

← Back to Overview

This guide will help you migrate your integration from Symtrain Public APIs v1 to v2. API v2 offers enhanced features, better performance, and additional endpoints for simulation management and user onboarding.

Why Migrate to v2?

New Capabilities in v2

✅ Simulation Management

• Get all available simulations from the library
• Assign/unassign simulations to specific users
• Full simulation lifecycle management

✅ Enhanced User Management

• Create individual users programmatically
• Bulk import users via CSV files
• Check bulk import task status
• Generate user-specific access tokens

✅ Improved Reports

• Additional data points and metrics
• Better structured response formats
• Enhanced filtering capabilities

✅ Better Developer Experience

• Consistent API patterns
• Improved error messages
• Enhanced documentation

---

Breaking Changes

✅ No Breaking Changes

Good news! If you're currently using v1 Reports API and Access API endpoints, your existing integration will continue to work. v2 is primarily additive - it adds new endpoints without breaking existing ones.

The main differences:

• URL path changes: Add /v2 prefix to endpoints
• Enhanced response structures: Same fields, plus additional data
• New optional parameters: Backward compatible

---

Endpoint Mapping

Reports API (All Endpoints Available in Both Versions)

v1 Endpoint	v2 Endpoint	Changes
POST /report/syms-result	POST /v2/report/syms-result	✅ Enhanced response data
POST /report/user-results	POST /v2/report/user-results	✅ Enhanced response data
POST /report/training-plan-result	POST /v2/report/training-plan-result	✅ Enhanced response data
POST /report/modules-results	POST /v2/report/modules-results	✅ Enhanced response data
POST /report/syms	POST /v2/report/syms	✅ Enhanced response data
POST /report/users	POST /v2/report/users	✅ Enhanced response data
POST /report/teams-result	POST /v2/report/teams-result	✅ Enhanced response data

Request Format: Identical (startDate, endDate, 3-month limit)
Response Format: Same structure with additional fields

---

Access API - Existing Endpoints

v1 Endpoint	v2 Endpoint	Changes
POST /access-api/simulation/deep-links	POST /v2/access-api/simulation/deep-links	✅ Same functionality
POST /access-api/simulation/completion-data	POST /v2/access-api/simulation/completion-data	✅ Enhanced - returns all execution attempts

---

Access API - New Endpoints in v2 Only

v2 Endpoint	Purpose
POST /v2/access-api/simulation/library	🆕 Get all available simulations
POST /v2/access-api/simulation/assignment	🆕 Assign/unassign simulations to users
POST /v2/access-api/user/token	🆕 Generate user access tokens (1 hour validity)
POST /v2/access-api/user/create	🆕 Create individual trainee users
POST /v2/access-api/user/bulk-import	🆕 Bulk import users via CSV
POST /v2/access-api/user/bulk-import/status	🆕 Check bulk import task status

---

Migration Steps

Step 1: Update Base URL

Add the /v2 prefix to your endpoints:

Before (v1):

Code
 
https://api.symtrain.com/report/user-results
https://api.symtrain.com/access-api/simulation/deep-links

After (v2):

Code
 
https://api.symtrain.com/v2/report/user-results
https://api.symtrain.com/v2/access-api/simulation/deep-links

---

Step 2: Update Report Endpoints

Example: User Results Report

v1 Request:

Code
 
curl -X POST https://api.symtrain.com/report/user-results \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2024-01-01",
    "endDate": "2024-03-31"
  }'

v2 Request (same structure):

Code
 
curl -X POST https://api.symtrain.com/v2/report/user-results \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2024-01-01",
    "endDate": "2024-03-31"
  }'

Response Changes:

• ✅ All v1 fields remain present
• ✅ Additional fields may be included
• ✅ Your existing code continues to work

---

Step 3: Update Access API Endpoints

Example: Generate Simulation Deep-links

v1:

Code
 
POST /access-api/simulation/deep-links

v2:

Code
 
POST /v2/access-api/simulation/deep-links

Request body: Identical
Response: Same structure

---

Step 4: Leverage New v2 Features (Optional)

Take advantage of new capabilities:

New Feature 1: Simulation Library

Get all available simulations:

Code
 
curl -X POST https://api.symtrain.com/v2/access-api/simulation/library \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "your-org-id",
    "userId": "user-id"
  }'

New Feature 2: Simulation Assignment

Assign a simulation to a user:

Code
 
curl -X POST https://api.symtrain.com/v2/access-api/simulation/assignment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "your-org-id",
    "userId": "user-id",
    "simulationId": "sim-id",
    "assign": true
  }'

New Feature 3: User Token Generation

Generate a 1-hour access token for user impersonation:

Code
 
curl -X POST https://api.symtrain.com/v2/access-api/user/token \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "your-org-id",
    "userId": "user-id"
  }'

Use the token in deep-links:

Code
 
https://symtrain.com/your-org-id/simulation/{simulationId}?token={generatedToken}

New Feature 4: Bulk User Import

Upload a CSV file to create/update multiple users:

Code
 
curl -X POST https://api.symtrain.com/v2/access-api/user/bulk-import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "organizationId=your-org-id" \
  -F "[email protected]"

CSV format:

Code
 
firstName,lastName,username,email,role,teamName,status,action
John,Doe,[email protected],[email protected],trainee,Sales,ACTIVE,Add

---

Code Migration Examples

Example 1: Reports Migration

Before (v1):

Code
 
async function getUserResults(startDate, endDate) {
  const response = await fetch("https://api.symtrain.com/report/user-results", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ startDate, endDate }),
  });
  return response.json();
}

After (v2):

Code
 
async function getUserResults(startDate, endDate) {
  const response = await fetch(
    "https://api.symtrain.com/v2/report/user-results",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ startDate, endDate }),
    }
  );
  return response.json();
}

Change: Add /v2 prefix to the endpoint

---

Example 2: Using New v2 Features

New: Complete User Onboarding Workflow

Code
 
async function onboardUser(orgId, email, firstName, lastName, simulationId) {
  // 1. Create user
  const createUserResponse = await fetch(
    "https://api.symtrain.com/v2/access-api/user/create",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        organizationId: orgId,
        email: email,
        username: email,
        firstName: firstName,
        lastName: lastName,
      }),
    }
  );
  const user = await createUserResponse.json();

  // 2. Assign simulation
  const assignResponse = await fetch(
    "https://api.symtrain.com/v2/access-api/simulation/assignment",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        organizationId: orgId,
        userId: user.userId,
        simulationId: simulationId,
        assign: true,
      }),
    }
  );
  const assignment = await assignResponse.json();

  // 3. Generate token
  const tokenResponse = await fetch(
    "https://api.symtrain.com/v2/access-api/user/token",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        organizationId: orgId,
        userId: user.userId,
      }),
    }
  );
  const { token } = await tokenResponse.json();

  // 4. Send deep-link with token
  const deepLink = `${assignment.deepLink}?token=${token}`;
  return { user, deepLink };
}

---

Migration Checklist

Use this checklist to track your migration progress:

Planning Phase

• Review all v1 endpoints currently in use
• Identify which new v2 features would benefit your integration
• Plan phased rollout approach
• Set up v2 testing environment

Implementation Phase

• Update base URLs from /v1 to /v2
• Update all report endpoint paths
• Update all access API endpoint paths
• Test all existing functionality works with v2
• Implement new v2 features (optional)
• Update error handling for new response formats

Testing Phase

• Test all report endpoints return expected data
• Test simulation deep-links generation
• Test completion data retrieval
• Test new features (if implemented)
• Verify rate limiting behavior (same as v1)
• Test error scenarios

Deployment Phase

• Deploy to staging environment
• Run integration tests
• Monitor API responses
• Deploy to production
• Monitor production metrics

Post-Migration

• Update internal documentation
• Train team on new v2 features
• Monitor API usage patterns
• Gather feedback from users

---

Common Migration Questions

Q: Do I need to migrate immediately?

A: No. v1 will continue to be supported for existing integrations. However, new features are only available in v2.

Q: Will my v1 integration break?

A: No. v1 endpoints remain fully functional. You can migrate at your own pace.

Q: Can I use both v1 and v2 simultaneously?

A: Yes. You can call v1 and v2 endpoints in the same application using the same API key.

Q: How long will v1 be supported?

A: v1 will be supported indefinitely for existing integrations. We recommend v2 for new features.

Q: Are there any performance differences?

A: v2 has the same performance characteristics as v1, with potential improvements in response times.

Q: Do I need a new API key for v2?

A: No. Your existing API key works for both v1 and v2.

---

Getting Help

If you encounter issues during migration:

1. Check the API Reference: View Interactive API Reference →
2. Review Best Practices: API Best Practices Guide →
3. Contact Support: [email protected]

---

Next Steps

1. Start Testing: Try v2 endpoints in your development environment
2. Explore New Features: Review the API v2 Guide for new capabilities
3. Plan Migration: Use our migration checklist
4. Deploy Gradually: Migrate endpoint by endpoint

---

← Back to Overview | View API v2 Guide →