Tutorials

Getting Started Tutorial

Copy page

← Back to Tutorials

Overview

This tutorial will walk you through making your first API call to the Symtrain Public APIs. By the end, you'll understand how to authenticate, make requests, and handle responses.

Duration: 10 minutes
Level: Beginner

---

Prerequisites

Before you begin, ensure you have:

• ✅ An API key (contact [email protected] if you don't have one)
• ✅ A tool for making HTTP requests (cURL, Postman, or your programming language of choice)
• ✅ Your organization ID

---

Step 1: Test Authentication

Let's verify your API key works by making a simple request.

cURL Example:

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": "test-user-id"
  }'

Expected Response (200 OK):

Code
 
{
  "simulations": [
    {
      "id": "sim-123",
      "title": "Customer Service Basics",
      "type": "audio",
      ...
    }
  ]
}

Common Errors:

• 401 Unauthorized: Check your API key
• 400 Bad Request: Verify your organizationId and JSON format

---

Step 2: Understanding Rate Limits

The Symtrain API allows 100 requests per 5-minute window per IP address.

Handling Rate Limits:

Code
 
if (response.status === 429) {
  // Wait and retry after some time
}

---

Step 3: Making Your First Meaningful Request

Let's get a user results report for the last 30 days.

Request:

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-10-01",
    "endDate": "2024-10-31"
  }'

Response Structure:

Code
 
{
  "results": [
    {
      "userId": "user-123",
      "userName": "John Doe",
      "email": "[email protected]",
      "completedSimulations": 5,
      "averageScore": 85.5,
      ...
    }
  ],
  "totalRecordsCount": 150,
  "page": 1,
  "pageSize": 100
}

---

Step 4: Error Handling

Always implement proper error handling:

JavaScript Example:

Code
 
async function makeApiCall() {
  try {
    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: "2024-10-01",
          endDate: "2024-10-31",
        }),
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.message}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error("Failed to fetch data:", error);
    throw error;
  }
}

---

Testing Your Implementation

Use this checklist to verify your setup:

• Authentication works (receive 200 response)
• Can retrieve simulation library
• Can generate a report
• Error handling catches 400/401/429 errors
• Rate limits are respected

---

Next Steps

Now that you've made your first API call, explore:

1. Generate Your First Report - Learn about different report types
2. Bulk User Import - Import multiple users at once
3. Best Practices - Optimize your API usage

---

Common Questions

Q: How do I get an API key?
A: Contact [email protected] with your organization details.

Q: What's the API response time?
A: Typical response times are 200-500ms for most endpoints.

---

← Back to Tutorials | Next: First Report →