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
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
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
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."
}
}
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"
}
}
]
}
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"]
}
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
- Export Google Forms responses to CSV
- Format CSV with two columns: "Master Schools" and "Submitted Schools"
- Upload CSV to /upload-csv endpoint
- Get instant report + auto-saved to history
- View past checks at /history endpoint