Skip to main content

​
1. API Purpose

The Write To module provides a structured ticketing system for parent-to-school communication. It replaces informal calls/notes with trackable threads for leave requests, complaints, and queries.

​
2. Endpoint Definition

MethodRouteAuthDescription
POST/parent-app/write-to🔐 JWTSubmit a new request
GET/parent-app/write-to🔐 JWTView active/past requests
GET/parent-app/write-to/:id🔐 JWTView full conversation thread
POST/parent-app/write-to/:id/reply🔐 JWTParent reply to a conversation
GET/teachers-app/write-to🔐 JWTStaff: View all school requests
POST/teachers-app/write-to/:id/reply🔐 JWTStaff: reply to a request
PUT/teachers-app/write-to/:id🔐 JWTStaff: Update status (e.g., Resolve)

​
3. Authentication Flow

Standard JWT validation.
  • Parents can only see requests they created (parent_id match).
  • Staff can see all requests for their school (skole_id match).

​
4. Request Structure

​
POST /parent-app/write-to

Request Body: 
{
  "skole_id": "SKL001",
  "parent_id": 1,
  "student_id": 45,
  "request_type": "leave_request",
  "subject": "Medical Leave for Aarav",
  "message": "Aarav has a mild fever...",
  "leave_from_date": "2024-03-17",
  "leave_to_date": "2024-03-17",
  "priority": "normal"
}

​
GET /parent-app/write-to

Query Parameters:
FieldTypeRequiredDescription
statusstringNoFilter by status (open/resolved).

​
GET /parent-app/write-to/:id

URL Parameters:
FieldTypeDescription
idnumberID of the request thread.

​
POST /parent-app/write-to/:id/reply

Request Body: 
{
  "replied_by_id": 1,
  "message": "Thank you for the update."
}

​
GET /teachers-app/write-to

Query Parameters:
FieldTypeRequiredDescription
skole_idstringYesSchool identifier.
staff_idstringNoFilter by assigned staff.
statusstringNoFilter by status (pending/resolved).
request_typestringNoFilter by type.

​
POST /teachers-app/write-to/:id/reply

Request Body: 
{
  "skole_id": "SKL001",
  "replied_by_id": 10,
  "message": "Get well soon!",
  "attachment_url": "..."
}

​
PUT /teachers-app/write-to/:id

Request Body: 
{
  "staff_id": 10,
  "status": "resolved"
}

​
5. Response Structure

​
Success: Request Submitted (201 Created)

Route: POST /parent-app/write-to 
{
  "success": true,
  "message": "Request submitted",
  "data": { "id": 102 }
}

​
Success: Parent Request List (200 OK)

Route: GET /parent-app/write-to 
{
  "success": true,
  "data": [
    {
      "id": 102,
      "subject": "Medical Leave",
      "status": "open",
      "created_at": "2024-03-16T09:00:00Z"
    }
  ]
}

​
Success: Full Thread View (200 OK)

Route: GET /parent-app/write-to/:id 
{
  "success": true,
  "data": {
    "request": { "id": 102, "subject": "Medical Leave", "status": "open" },
    "replies": [
      { "id": 1, "message": "Get well soon!", "replied_by_id": 10 }
    ]
  }
}

​
Success: Staff Request Queue (200 OK)

Route: GET /teachers-app/write-to 
{
  "success": true,
  "data": [
    {
      "id": 102,
      "parent_name": "Rajesh Kumar",
      "subject": "Medical Leave",
      "status": "pending"
    }
  ]
}

​
Success: Reply Posted (201 Created)

Route: POST /{module}/write-to/:id/reply 
{
  "success": true,
  "message": "Reply sent successfully"
}

​
Success: Ticket Resolved (200 OK)

Route: PUT /teachers-app/write-to/:id 
{
  "success": true,
  "message": "Request marked as resolved"
}

​
6. Error Responses

HTTP CodeDescription
403Forbidden: Attempting to access a request belonging to another parent
400Missing leave_from_date for a leave type request

​
7. Security Considerations

  • Thread Integrity: Replies are linked via write_to_id.
  • Role Scoping: Only staff with specific permissions can resolve tickets or assign them to others.

​
8. Token Usage

POST /parent-app/write-to
Authorization: Bearer <TOKEN>

​
9. Token Refresh

N/A.

​
10. Logout / Session Invalidation

N/A.

​
11. Usage Example (cURL)

curl -X POST http://localhost:3000/parent-app/write-to \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"subject": "Query about Fee", "message": "...", "request_type": "query"}'

​
12. Notes / Special Behaviors

  • Leave Logic: Submitting a leave type request automatically notifies the class teacher via push notification.
  • Auto-Close: Inactive resolved threads are archived after a defined period (e.g., 30 days).