SOBIE Conference API Documentation

Name Card Generation API

Overview

The Name Card Generation API allows administrators to create professional, printable name cards for conference attendees. Each name card includes:

Features

🎨 Professional Design

📊 Attendee Classification

🏆 Conference History Tracking

🖨️ Print-Ready Output

API Endpoints

Generate All Name Cards

GET /api/admin/name-cards/generate?conferenceId={id}&format=pdf&includeLogos=true

Description: Generate name cards for all confirmed attendees of a conference.

Query Parameters:

Response: PDF file download

Example:

curl -X GET "http://localhost:3000/api/admin/name-cards/generate?conferenceId=507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -o "conference-name-cards.pdf"

Generate Single Name Card

GET /api/admin/name-cards/attendee/{registrationId}?format=pdf&includeLogos=true

Description: Generate a name card for a specific attendee.

Path Parameters:

Query Parameters:

Response: PDF file download

Example:

curl -X GET "http://localhost:3000/api/admin/name-cards/attendee/507f1f77bcf86cd799439012" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -o "john-doe-name-card.pdf"

Get Name Card Preview

GET /api/admin/name-cards/preview/{registrationId}

Description: Get preview data for a name card without generating the PDF.

Path Parameters:

Response:

{
  "success": true,
  "data": {
    "nameCard": {
      "preferredName": "Dr. Jane Smith",
      "fullName": "Jane Marie Smith",
      "affiliation": "University of Example",
      "university": "University of Example",
      "attendeeType": "academic",
      "isFirstTime": false,
      "sobieCount": 3,
      "conferenceYear": 2024,
      "email": "jane.smith@example.edu",
      "registrationId": "507f1f77bcf86cd799439012"
    },
    "attendeeHistory": {
      "totalSOBIEsAttended": 3,
      "isFirstTime": false,
      "previousConferences": [
        {
          "year": 2022,
          "title": "SOBIE 2022: Innovation in Biomedical Engineering"
        },
        {
          "year": 2023,
          "title": "SOBIE 2023: Future Technologies"
        },
        {
          "year": 2024,
          "title": "SOBIE 2024: Sustainable Solutions"
        }
      ]
    }
  }
}

Get Attendees List

GET /api/admin/name-cards/attendees/{conferenceId}?page=1&limit=50&search=smith

Description: Get a paginated list of attendees with name card data for bulk generation.

Path Parameters:

Query Parameters:

Response:

{
  "success": true,
  "data": {
    "attendees": [
      {
        "registrationId": "507f1f77bcf86cd799439012",
        "nameCard": {
          "preferredName": "Dr. Jane Smith",
          "fullName": "Jane Marie Smith",
          "affiliation": "University of Example",
          "university": "University of Example",
          "attendeeType": "academic",
          "isFirstTime": false,
          "sobieCount": 3,
          "conferenceYear": 2024,
          "email": "jane.smith@example.edu",
          "registrationId": "507f1f77bcf86cd799439012"
        },
        "selected": false
      }
    ],
    "pagination": {
      "current": 1,
      "pages": 5,
      "total": 247,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Authentication & Authorization

All name card endpoints require:

Headers Required:

Authorization: Bearer {your-jwt-token}
Content-Type: application/json

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Conference ID is required",
  "statusCode": 400
}

401 Unauthorized

{
  "success": false,
  "message": "Authentication required",
  "statusCode": 401
}

403 Forbidden

{
  "success": false,
  "message": "Admin access required",
  "statusCode": 403
}

404 Not Found

{
  "success": false,
  "message": "No confirmed registrations found for this conference",
  "statusCode": 404
}

Data Models

Attendee Data Structure

{
  preferredName: String,      // Display name on badge
  fullName: String,           // Full legal name
  affiliation: String,        // Primary affiliation
  university: String,         // University name
  attendeeType: String,       // student|academic|sobie_affiliate|professional|industry
  isFirstTime: Boolean,       // First SOBIE conference
  sobieCount: Number,         // Total SOBIEs attended
  conferenceYear: Number,     // Current conference year
  email: String,              // Contact email
  registrationId: ObjectId    // Registration reference
}

Attendee Types

Technical Implementation

PDF Generation

Image Processing

Performance Considerations

Usage Examples

Frontend Integration (React)

// Generate all name cards for a conference
const generateAllNameCards = async (conferenceId) => {
  try {
    const response = await fetch(
      `/api/admin/name-cards/generate?conferenceId=${conferenceId}&includeLogos=true`,
      {
        method: 'GET',
        headers: {
          'Authorization': `Bearer ${token}`,
        },
      }
    );
    
    if (response.ok) {
      const blob = await response.blob();
      const url = window.URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url;
      a.download = `conference-${conferenceId}-name-cards.pdf`;
      a.click();
      window.URL.revokeObjectURL(url);
    }
  } catch (error) {
    console.error('Error generating name cards:', error);
  }
};

// Get attendees list for selection
const getAttendeesList = async (conferenceId, page = 1, search = '') => {
  try {
    const response = await fetch(
      `/api/admin/name-cards/attendees/${conferenceId}?page=${page}&search=${encodeURIComponent(search)}`,
      {
        method: 'GET',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json',
        },
      }
    );
    
    if (response.ok) {
      return await response.json();
    }
  } catch (error) {
    console.error('Error fetching attendees:', error);
  }
};

Command Line Usage

# Generate all name cards for a conference
curl -X GET "http://localhost:3000/api/admin/name-cards/generate?conferenceId=507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o "conference-name-cards.pdf"

# Generate single name card
curl -X GET "http://localhost:3000/api/admin/name-cards/attendee/507f1f77bcf86cd799439012" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o "attendee-name-card.pdf"

# Get preview data
curl -X GET "http://localhost:3000/api/admin/name-cards/preview/507f1f77bcf86cd799439012" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Future Enhancements

Planned Features

Integration Opportunities

Troubleshooting

Common Issues

  1. Missing Dependencies 
    npm install pdfkit sharp axios
  2. Memory Issues with Large Batches
    • Process in smaller chunks
    • Increase Node.js memory limit: node --max-old-space-size=4096
  3. University Logo Loading Failures
    • Logos gracefully degrade to text-only
    • Check network connectivity for external logo APIs
    • Consider maintaining local logo database
  4. PDF Generation Errors
    • Ensure sufficient disk space for temporary files
    • Check write permissions in output directory
    • Validate attendee data completeness

Support

For technical support or feature requests, please contact the SOBIE development team or create an issue in the project repository.