🎓 Invite Student to Course API

This API endpoint allows you to invite students to courses using API token authentication. It creates new user accounts for non-existing users and adds existing users to the specified course.

📍 Endpoint

🔐 Authentication

This endpoint requires API token authentication. You must include a valid API token in the Authorization header.

Header Format:

Authorization: Bearer <your-api-token>

📝 Request Parameters

Request Body (JSON):

Example Request:

POST /inviteStudentToCourse
Content-Type: application/json
Authorization: Bearer your-api-token-here

{
    "schoolId": "school123",
    "productId": "course456",
    "email": "student@example.com",
    "accessMonths": 12
}

📅 Access Period & Invitation Cost

How the access window is calculated

Access is granted as a duration, not as a calendar date. On success the student's expiry (paidUntil) is always calculated from the moment the request is processed:

paidUntil = <time of the API call> + accessMonths

Months are added as calendar months, so a 6-month invitation created on 15 January expires on 15 July.

Invitation cost

Each newly enrolled student consumes invitations from your school's balance. The amount depends on accessMonths and on whether your school is on custom pricing:

Examples on standard pricing:

📤 Response Format

Success Response (200):

{
    "success": true,
    "brokenEmails": []
}

success is true only when the student was actually added to the course. Every other outcome returns HTTP 400.

Error Response:

{
    "success": false,
    "error": "Error description",
    "required": 2,             // Only for insufficient balance: total cost of the request
    "available": 1,            // Only for insufficient balance: current balance
    "invitationsPerUser": 2,   // Only for insufficient balance: cost implied by accessMonths
    "customPricing": false     // Only for insufficient balance: which cost formula applied
}

📊 Status Codes

⚡ Features

• Automatic User Creation: Creates new Firebase Auth users for non-existing emails
• Email Notifications: Sends welcome emails with login credentials
• Multi-language Support: Supports Ukrainian, English, Russian, and Polish emails
• Configurable Access Period: Set the access duration per invitation via accessMonths
• Invitation Balance: Deducted in a transaction and refunded automatically on failure
• Duplicate Prevention: Prevents adding users already in the course
• Role Management: Automatically assigns student role

🚫 Limitations

📋 Example Usage

JavaScript/Node.js:

const inviteStudent = async (schoolId, productId, email, apiToken, accessMonths) => {
    try {
        const response = await fetch('https://invitestudenttocourse-s4mogebb3q-lm.a.run.app', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${apiToken}`
            },
            body: JSON.stringify({
                schoolId: schoolId,
                productId: productId,
                email: email,
                // Optional. Omit to use the 6-month default.
                // Must be a number, not a string.
                ...(accessMonths ? { accessMonths: Number(accessMonths) } : {})
            })
        });

        const result = await response.json();

        if (response.ok && result.success) {
            console.log('Student invited successfully!');
            return result;
        } else {
            console.error('Failed to invite student:', result.error || result.brokenEmails);
            throw new Error(result.error || 'Student could not be enrolled');
        }
    } catch (error) {
        console.error('Request failed:', error);
        throw error;
    }
};

// Usage
inviteStudent('school123', 'course456', 'student@example.com', 'your-api-token', 12)
    .then(result => console.log('Success:', result))
    .catch(error => console.error('Error:', error));

Python:

import requests

def invite_student(school_id, product_id, email, api_token, access_months=None):
    url = "https://invitestudenttocourse-s4mogebb3q-lm.a.run.app"

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_token}"
    }

    data = {
        "schoolId": school_id,
        "productId": product_id,
        "email": email
    }

    # Optional. Omit to use the 6-month default. Must be an int, not a string.
    if access_months is not None:
        data["accessMonths"] = int(access_months)

    try:
        response = requests.post(url, headers=headers, json=data)
        result = response.json()

        if response.status_code == 200 and result.get('success'):
            print("Student invited successfully!")
            return result

        error_msg = result.get('error') or f"Not enrolled: {result.get('brokenEmails')}"
        print(f"Failed to invite student: {error_msg}")
        raise Exception(error_msg)

    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        raise

# Usage
try:
    result = invite_student('school123', 'course456', 'student@example.com', 'your-api-token', 12)
    print("Success:", result)
except Exception as e:
    print("Error:", e)

cURL:

curl -X POST \
  https://invitestudenttocourse-s4mogebb3q-lm.a.run.app \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-token' \
  -d '{
    "schoolId": "school123",
    "productId": "course456",
    "email": "student@example.com",
    "accessMonths": 12
  }'

🔧 Error Handling Examples

Invalid Email Format:

// Request
{
    "schoolId": "school123",
    "productId": "course456",
    "email": "invalid-email"
}

// Response (400)
{
    "success": false,
    "error": "Invalid email format"
}

Insufficient Invitation Balance:

// Request — 12 months costs 2 invitations on standard pricing
{
    "schoolId": "school123",
    "productId": "course456",
    "email": "student@example.com",
    "accessMonths": 12
}

// Response (400)
{
    "success": false,
    "error": "Not enough invitation balance",
    "required": 2,
    "available": 1,
    "invitationsPerUser": 2,
    "customPricing": false
}

Shared Material Product:

// Request
{
    "schoolId": "school123",
    "productId": "shm-abc123",
    "email": "student@example.com"
}

// Response (403)
{
    "success": false,
    "error": "Cannot invite students to shared materials via API"
}

Student Already in Course:

// Response (400)
{
    "success": false,
    "brokenEmails": ["student@example.com"]
}

Email Belongs to a Non-Student Account:

// Response (400) — the account already exists as a teacher or admin.
// It is left untouched and is NOT listed in brokenEmails.
{
    "success": false,
    "brokenEmails": []
}