API Reference

Complete REST API documentation for integrating with SchoolPalm.

Base URL

https://api.schoolpalm.io/v1

Authentication

All API requests require a Bearer token passed in the Authorization header:

curl -X GET https://api.schoolpalm.io/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate Limiting

Default Limit: 1000 requests/hour
Headers:
- X-RateLimit-Limit: Maximum requests
- X-RateLimit-Remaining: Requests remaining
- X-RateLimit-Reset: Unix timestamp when limit resets

Error Handling

All errors return a JSON response with an error code and message:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: name",
    "status": 400
  }
}

Common Error Codes

Code	Status	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request data
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Server error

Schools API

List Schools

GET /schools

Query Parameters:

limit (integer): Results per page (default: 20)
offset (integer): Pagination offset (default: 0)
search (string): Search by school name or code

Response:

{
  "data": [
    {
      "id": "school-123",
      "name": "Central High School",
      "code": "CHS001",
      "city": "New York",
      "country": "USA",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150
  }
}

Get School

GET /schools/:id

Response:

{
  "id": "school-123",
  "name": "Central High School",
  "code": "CHS001",
  "city": "New York",
  "country": "USA",
  "principal": "Dr. Jane Smith",
  "email": "info@chs.edu",
  "phone": "+1-555-0123",
  "studentCount": 850,
  "staffCount": 75,
  "createdAt": "2024-01-15T10:00:00Z"
}

Create School

POST /schools
Content-Type: application/json

{
  "name": "New High School",
  "code": "NHS001",
  "city": "Boston",
  "country": "USA",
  "principal": "Dr. John Doe"
}

Students API

List Students

GET /schools/:schoolId/students

Query Parameters:

class (string): Filter by class
status (string): Filter by status (active, inactive, graduated)
search (string): Search by name or roll number

Response:

{
  "data": [
    {
      "id": "student-456",
      "name": "Alice Johnson",
      "rollNumber": "101",
      "class": "10A",
      "email": "alice@example.com",
      "status": "active",
      "enrollmentDate": "2023-06-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 800
  }
}

Get Student

GET /students/:id

Create Student

POST /schools/:schoolId/students
Content-Type: application/json

{
  "name": "Bob Smith",
  "rollNumber": "102",
  "class": "10A",
  "email": "bob@example.com",
  "parentName": "Mr. Smith",
  "parentEmail": "parent@example.com",
  "parentPhone": "+1-555-9999"
}

Attendance API

Mark Attendance

POST /schools/:schoolId/attendance
Content-Type: application/json

{
  "date": "2024-06-09",
  "records": [
    {
      "studentId": "student-456",
      "status": "present"
    },
    {
      "studentId": "student-457",
      "status": "absent",
      "reason": "Medical leave"
    }
  ]
}

Get Attendance Report

GET /students/:studentId/attendance

Query Parameters:

from (date): Start date (YYYY-MM-DD)
to (date): End date (YYYY-MM-DD)

Response:

{
  "studentId": "student-456",
  "name": "Alice Johnson",
  "totalDays": 100,
  "presentDays": 95,
  "absentDays": 3,
  "leaveDays": 2,
  "attendancePercentage": 95.0,
  "records": [
    {
      "date": "2024-06-09",
      "status": "present"
    }
  ]
}

Webhooks

Subscribe to real-time events from SchoolPalm.

Supported Events

school.created
school.updated
student.enrolled
student.graduated
attendance.marked
exam.scheduled
result.published

Register Webhook

POST /webhooks
Content-Type: application/json

{
  "url": "https://yourapp.com/webhooks/schoolpalm",
  "events": ["student.enrolled", "attendance.marked"]
}

Webhook Payload

{
  "id": "webhook-789",
  "event": "student.enrolled",
  "timestamp": "2024-06-09T10:30:00Z",
  "data": {
    "studentId": "student-456",
    "schoolId": "school-123",
    "name": "Alice Johnson"
  }
}

Pagination

Use limit and offset for pagination:

# First page
GET /schools?limit=20&offset=0

# Second page
GET /schools?limit=20&offset=20

API SDKs

Use our official SDKs for easier integration:

Testing

Use the API Sandbox for testing without affecting production data.

Support

For API support, visit GitHub Discussions or email support@schoolpalm.io.