Documentation

Frequently Asked Questions

Copy page

Quick answers to common questions about the SymTrain Public APIs.

---

Authentication

How do I get an API key?

Contact your SymTrain account manager or email [email protected] with:

• Your organization name
• Intended use case
• Expected request volume

API keys are typically provisioned within 1-2 business days.

---

Rate Limits

What are the rate limits?

100 requests per 5 minutes per API key.

Rate limit resets every 5 minutes from your first request.

---

What happens if I exceed the rate limit?

You'll receive a 429 Too Many Requests response. Implement exponential backoff and retry logic. See Best Practices.

---

Can I request a higher rate limit?

Yes. Contact [email protected] with:

• Your current API key
• Justification for higher limits
• Expected request patterns

---

Data & Reports

What's the maximum date range for reports?

3 months (180 days) maximum.

For longer ranges, make multiple requests with sequential date ranges.

---

How do I handle pagination?

Increment the page parameter and continue until results.length < pageSize:

Code
 
let page = 1;
let hasMore = true;

while (hasMore) {
  const data = await getReport({ page, pageSize: 100 });
  hasMore = data.results.length === data.pageSize;
  page++;
}

See Best Practices - Pagination.

---

Are reports real-time?

Reports reflect data processed up to the last completed batch job (typically within 15 minutes of activity).

---

Can I get historical data beyond 3 months?

Yes, but you must make multiple API calls with different date ranges:

Code
 
// Get 6 months of data
const firstThreeMonths = await getReport({
  startDate: "2024-07-01",
  endDate: "2024-09-30",
});

const secondThreeMonths = await getReport({
  startDate: "2024-10-01",
  endDate: "2024-12-31",
});

---

Bulk Import

What's the CSV format for bulk import?

Code
 
firstName,lastName,username,email,role,teamName,status,action

• Required columns: All 8 columns
• Max records: 750 per file
• Email requirement: Must match username
• Role: Only "trainee" supported

See CSV Format Documentation.

---

How do I track bulk import progress?

Use the /bulk-import/status endpoint with the taskId returned from the upload:

Code
 
curl -X POST https://api.symtrain.com/v2/access-api/user/bulk-import/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"organizationId": "org-id", "taskId": "task-123"}'

---

What happens if some rows fail validation?

The API validates all rows before processing. If any row fails:

• No users are created
• Response includes detailed error list with row numbers
• Fix errors and re-upload

---

Can I import more than 750 users?

Yes - split into multiple CSV files of 750 records each and upload sequentially.

---

Simulations

How do I get a list of available simulations?

Use the /v2/access-api/simulation/library endpoint:

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

---

How long are user access tokens valid?

1 hour from generation.

Generate tokens just-in-time, not in advance.

---

Can I assign multiple simulations at once?

No - assignments are individual. However, you can parallelize requests:

Code
 
const simulationIds = ["sim-1", "sim-2", "sim-3"];

await Promise.all(
  simulationIds.map((simId) => assignSimulation(orgId, userId, simId))
);

---

How do I know when a user completes a simulation?

Use /v2/access-api/simulation/completion-data:

Code
 
curl -X POST https://api.symtrain.com/v2/access-api/simulation/completion-data \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "organizationId": "org-id",
    "userId": "user-id",
    "simulationId": "sim-id"
  }'

Check the completedAt field - if null, simulation is incomplete.

---

API Versions

Should I use v1 or v2?

Use v2 for new integrations. v2 offers:

• Bulk user import
• Simulation management
• User token generation
• Completion tracking

v1 remains supported for existing integrations.

---

Is there a difference between v1 and v2 reports?

No - report endpoints are identical. v2 adds new functionality without changing existing endpoints.

---

Errors & Troubleshooting

Why am I getting 401 Unauthorized?

Common causes:

• Invalid API key
• Expired API key
• Incorrect Authorization header format

Verify header format: Authorization: Bearer YOUR_API_KEY

---

Why am I getting 400 Bad Request?

Check:

• Request body JSON is valid
• Required fields are present
• Date formats are correct (YYYY-MM-DD)
• Date range is ≤ 180 days

---

Why am I getting "Resource not found" errors?

Verify:

• Organization ID is correct
• User ID exists in the system
• Simulation ID is in the organization's library

---

Best Practices

Should I cache API responses?

Yes, for:

• Simulation library (changes infrequently)
• Organization metadata

No, for:

• Reports (data updates regularly)
• User completion data

---

How should I handle errors?

Implement:

1. Retry logic with exponential backoff
2. Rate limit handling
3. Comprehensive error logging
4. Graceful degradation

See Best Practices - Error Handling.

---

Still Have Questions?

• Documentation: API Reference
• Tutorials: Getting Started
• Email: [email protected]

---