groups Get Students List Endpoint

Endpoint Details

Endpoint: GET /smrtapi/v1/students

Purpose: Retrieve a paginated list of students with summary statistics. Perfect for roster exports, SIS integration, and batch reporting.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (must be ≥ 1)
limit	integer	50	Results per page (1-100)
class_id	integer	-	Filter by specific class
course_id	integer	-	Filter by course enrollment
search	string	-	Search by name, email, or reference ID

Headers Required

X-API-Key: your_institution_api_key

Example Requests

# Get first page (default 50 students)
curl -H "X-API-Key: your_institution_api_key" \
  https://smrtenglish.com/smrtapi/v1/students

# Get specific page with custom limit
curl -H "X-API-Key: your_institution_api_key" \
  "https://smrtenglish.com/smrtapi/v1/students?page=2&limit=25"

# Filter by class
curl -H "X-API-Key: your_institution_api_key" \
  "https://smrtenglish.com/smrtapi/v1/students?class_id=456"

Response Example (abbreviated):

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "email": "[email protected]",
      "name": "John Doe",
      "classes": [
        {
          "class_id": 456,
          "class_title": "English 101 - Section A",
          "course_name": "General English"
        },
        {
          "class_id": 457,
          "class_title": "English 102 - Section B",
          "course_name": "Business English"
        }
      ],
      "summary": {
        "total_assignments": 45,
        "completed_assignments": 40,
        "completion_rate": 88.9,
        "average_score": 85.5,
        "total_time_minutes": 450.5
      },
      "activity_tracking": {
        "first_login_date": "2024-01-15",
        "last_activity_date": "2024-10-10",
        "days_since_last_activity": 5,
        "assignment_submission_count": 40,
        "assignment_missing_count": 5,
        "has_ever_logged_in": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_count": 247,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

Note: Only registered students are returned. Unregistered students are automatically excluded.

Use Cases

• Student Roster Export - Pull complete student lists for SIS integration or Excel reports
• Batch Progress Reports - Generate reports across all students or filtered by class
• At-Risk Student Identification - Find students with low completion rates or scores
• Class Performance Analytics - Compare performance across different classes or courses
• Automated Workflows - Sync student data to external systems on a schedule
• Dashboard Visualizations - Create real-time dashboards showing student progress

Pagination Best Practices

• Use limit=100 for bulk exports to minimize API calls
• Check has_next in pagination response to know if more data is available
• Process pages sequentially to avoid missing data
• Cache responses for 5-15 minutes to reduce API load

Example: Export All Students

import requests

api_key = "your_institution_api_key"
base_url = "https://smrtenglish.com/smrtapi/v1/students"
headers = {"X-API-Key": api_key}

all_students = []
page = 1

while True:
    response = requests.get(
        base_url,
        headers=headers,
        params={"page": page, "limit": 100}
    )
    data = response.json()

    all_students.extend(data["data"])

    if not data["pagination"]["has_next"]:
        break

    page += 1

print(f"Retrieved {len(all_students)} students")

Response Format

Returns a paginated list of students with summary statistics:

Complete Response Structure

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "email": "[email protected]",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "reference_id": "STU-2024-001",
      "profile_image": "https://example.com/profile.jpg",
      "registration_date": "2024-01-15",
      "is_registered": 1,
      "classes": [
        {
          "class_id": 456,
          "class_title": "English 101 - Section A",
          "course_name": "General English"
        },
        {
          "class_id": 457,
          "class_title": "English 102 - Section B",
          "course_name": "Business English"
        }
      ],
      "summary": {
        "total_assignments": 45,
        "completed_assignments": 40,
        "completion_rate": 88.9,
        "average_score": 85.5,
        "total_assessments": 8,
        "completed_assessments": 6,
        "total_time_minutes": 450.5,
        "last_activity_date": "2024-09-28"
      }
    },
    {
      "id": 12346,
      "email": "[email protected]",
      "name": "Jane Smith",
      "first_name": "Jane",
      "last_name": "Smith",
      "reference_id": "STU-2024-002",
      "registration_date": "2024-01-16",
      "is_registered": 1,
      "summary": {
        "total_assignments": 45,
        "completed_assignments": 42,
        "completion_rate": 93.3,
        "average_score": 91.2,
        "total_assessments": 8,
        "completed_assessments": 7,
        "total_time_minutes": 520.8,
        "last_activity_date": "2024-09-29"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_count": 247,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

Response Fields

Student Object:

Field	Type	Description
id	integer	Unique student user ID
email	string	Student email address
reference_id	string	Your institution's student ID
classes	array	Array of classes student is enrolled in. Each object contains class_id (integer), class_title (string), and course_name (string). Empty array if student is not enrolled in any active classes.
summary.completion_rate	float	Assignment completion percentage (0-100)
summary.average_score	float	Average assignment score (0-100, null if none)
summary.total_time_minutes	float	Total learning time in minutes

Pagination Object:

• page - Current page number
• limit - Items per page
• total_count - Total students matching filters
• total_pages - Total pages available
• has_next - Boolean, true if more pages exist
• has_prev - Boolean, true if previous page exists

Note: For detailed student data including courses, classes, and individual assignments, use the Get Student Data endpoint.