🎓 School Submission Tracker API v2.0

Automated school data collection tracking for EMIS officers

🟢 API Online

Overview

A serverless AWS REST API that helps Education Management Information System (EMIS) officers track school data submissions efficiently. The API is currently online, secured with AWS Secrets Manager authentication, and 30-day history tracking using DynamoDB.

Features

Instant Comparison
Compare submitted schools list against master school list in seconds!
Duplicate Detection
Automatically detects schools that submitted multiple times
Completion Rates
Calculate submission progress and completion percentages
CSV Upload NEW
Eliminate JSON fromatting. Upload files directly!
30-Day History Tracking NEW
Track submission progress over time
Auto-Cleanup NEW
DynamoDB TTL removes old data automatically

Security Note

Fail-Closed Authentication: If the API key configuration cannot be loaded from Secrets Manager for any reason, all authenticated endpoints return 503 Service Unavailable.

🔗 Endpoints

POST /upload-csv NEW

Description: Upload CSV with master and submitted schools

Content-Type: multipart/form-data

Authentication: API key required (disabled in local testing mode)

CSV File Format (test-data.csv):

Master Schools,Submitted Schools
SCHOOL A,SCHOOL A
SCHOOL B,
SCHOOL C,SCHOOL C
💡 Tip: Save your school lists to an actual file (e.g. test-data.csv) and reference it with -F "file=@test-data.csv" — easier to reuse and re-run than retyping data inline.

Example:

curl -X POST http://localhost:3000/upload-csv   -H "x-api-key: YOUR-API-KEY"   -F "file=@test-data.csv"

Expected Response:

{
  "check_id": "a1b2c3d4-...",
  "collection_date": "2026-07-21",
  "summary": {
    "total_schools": 18,
    "unique_schools_submitted": 9,
    "missing_schools": 9,
    "completion_rate": "50.0%",
    "status": "In progress - Keep sending reminders"
  },
  "missing_schools": ["SCHOOL J", "SCHOOL K", ...],
  "submitted_schools": ["SCHOOL A", "SCHOOL B", ...],
  "warnings": {
    "duplicates_found": 1,
    "message": "1 school(s) submitted multiple times."
  }
}
GET /history?limit=10 NEW

Description: View recent submission checks (last 30 days)

Authentication: API key required (disabled in local mode)

Query Parameters: limit (default: 10, max: 50)

Example:

curl -X GET "http://localhost:3000/history?limit=5"   -H "x-api-key: YOUR-API-KEY"

Expected Response:

{
  "total_records": 1,
  "retention_days": 30,
  "history": [
    {
      "check_id": "a1b2c3d4-...",
      "collection_date": "2026-07-21",
      "summary": {
        "total_schools": 18,
        "completion_rate": "50.0%",
        "status": "In progress - Keep sending reminders"
      }
    }
  ]
}
POST /check-submissions

Description: JSON endpoint (backward compatible)

Content-Type: application/json

Authentication: API key required (disabled in local mode)

Note: Use /upload-csv for easier workflow!

JSON File Format (test-data.json):

{
"master_schools": ["SCHOOL A", "SCHOOL B", "SCHOOL C"],
"submitted_schools": ["SCHOOL A", "SCHOOL C"]
}
💡 Tip: Save your school lists to an actual file (e.g. test-data.json) and reference it with -d "@test-data.json" instead of typing JSON inline.

Example:

curl -X POST https://YOUR-API-URL/check-submissions   -H "Content-Type: application/json"   -H "x-api-key: YOUR-API-KEY"   -d "@test-data.json"

Expected Response:

{
  "check_id": "a1b2c3d4-...",
  "summary": {
    "total_schools": 3,
    "unique_schools_submitted": 2,
    "missing_schools": 1,
    "completion_rate": "66.7%",
    "status": "In progress - Keep sending reminders"
  },
  "missing_schools": ["SCHOOL B"],
  "submitted_schools": ["SCHOOL A", "SCHOOL C"]
}

⚙️ Quick Start

  1. Export Google Forms responses to CSV
  2. Format CSV with two columns: "Master Schools" and "Submitted Schools"
  3. Upload CSV to /upload-csv endpoint
  4. Get instant report + auto-saved to history
  5. View past checks at /history endpoint

© 2026, Gloria Boakye - EMIS OFFICER, GES | AWS Community Builder (Serverless)