Tutorials

Bulk User Import Tutorial

Copy page

← Back to Tutorials

Overview

Import multiple users at once using CSV files. This is ideal for onboarding large numbers of trainees.

Duration: 20 minutes | Level: Intermediate

---

Prerequisites

• ✅ API key
• ✅ Organization ID
• ✅ CSV file with user data

---

Step 1: Prepare Your CSV File

Create a CSV with these exact column headers:

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

Rules:

• Maximum 750 records per file
• email must match username
• Only trainee role is supported
• status: ACTIVE or INACTIVE
• action: Add or Update

---

Step 2: Upload the CSV File

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]"

Response:

Code
 
{
  "taskId": "task-abc123",
  "validUsersCount": 48,
  "invalidUsersCount": 2,
  "errors": [
    {
      "row": 5,
      "errors": ["Email must match username"]
    }
  ]
}

---

Step 3: Monitor Import Status

Poll the status endpoint:

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

Status Values:

• SCHEDULED → Task queued
• STARTED → Processing
• COMPLETED → Success
• FAILED → Error occurred

---

Step 4: Handle Errors

Common validation errors:

Error	Solution
Email doesn't match username	Ensure email === username
Invalid role	Only "trainee" is supported
Missing required field	Check all required columns are present
File too large	Split into files of 750 records or less

---

Complete Workflow Example

Code
 
async function bulkImportUsers(csvFile, orgId) {
  // 1. Upload CSV
  const formData = new FormData();
  formData.append("organizationId", orgId);
  formData.append("file", csvFile);

  const uploadResponse = await fetch(
    "https://api.symtrain.com/v2/access-api/user/bulk-import",
    {
      method: "POST",
      headers: { Authorization: `Bearer ${API_KEY}` },
      body: formData,
    }
  );

  const { taskId, errors } = await uploadResponse.json();

  if (errors && errors.length > 0) {
    console.log("Validation errors:", errors);
  }

  // 2. Poll status
  let status = "SCHEDULED";
  while (status !== "COMPLETED" && status !== "FAILED") {
    await new Promise((resolve) => setTimeout(resolve, 5000)); // Wait 5 seconds

    const statusResponse = await fetch(
      "https://api.symtrain.com/v2/access-api/user/bulk-import/status",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ organizationId: orgId, taskId }),
      }
    );

    const statusData = await statusResponse.json();
    status = statusData.status;
    console.log(`Import status: ${status}`);
  }

  return status === "COMPLETED";
}

---

Testing

• CSV file formatted correctly
• Upload successful with taskId returned
• Status polling works
• Handled validation errors appropriately
• Verified users created in system

---

Next Steps

• Simulation Assignment Tutorial
• CSV Format Reference

---

← Back to Tutorials | Next: Simulation Assignment →