Write To (Parent Requests)

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

Method	Route	Auth	Description
POST	`/parent-app/write-to`	🔐 JWT	Submit a new request
GET	`/parent-app/write-to`	🔐 JWT	View active/past requests
GET	`/parent-app/write-to/:id`	🔐 JWT	View full conversation thread
POST	`/parent-app/write-to/:id/reply`	🔐 JWT	Parent reply to a conversation
GET	`/teachers-app/write-to`	🔐 JWT	Staff: View all school requests
POST	`/teachers-app/write-to/:id/reply`	🔐 JWT	Staff: reply to a request
PUT	`/teachers-app/write-to/:id`	🔐 JWT	Staff: 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:

Field	Type	Required	Description
status	string	No	Filter by status (open/resolved).

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

URL Parameters:

Field	Type	Description
id	number	ID 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:

Field	Type	Required	Description
skole_id	string	Yes	School identifier.
staff_id	string	No	Filter by assigned staff.
status	string	No	Filter by status (pending/resolved).
request_type	string	No	Filter 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 Code	Description
403	Forbidden: Attempting to access a request belonging to another parent
400	Missing `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).

Modules

API

Data Schema

Changelog

1. API Purpose

2. Endpoint Definition

3. Authentication Flow

4. Request Structure

POST /parent-app/write-to

GET /parent-app/write-to

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

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

GET /teachers-app/write-to

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

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

5. Response Structure

Success: Request Submitted (201 Created)

Success: Parent Request List (200 OK)

Success: Full Thread View (200 OK)

Success: Staff Request Queue (200 OK)

Success: Reply Posted (201 Created)

Success: Ticket Resolved (200 OK)

6. Error Responses

7. Security Considerations

8. Token Usage

9. Token Refresh

10. Logout / Session Invalidation

11. Usage Example (cURL)

12. Notes / Special Behaviors

​1. API Purpose

​2. Endpoint Definition

​3. Authentication Flow

​4. Request Structure

​POST /parent-app/write-to

​GET /parent-app/write-to

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

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

​GET /teachers-app/write-to

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

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

​5. Response Structure

​Success: Request Submitted (201 Created)

​Success: Parent Request List (200 OK)

​Success: Full Thread View (200 OK)

​Success: Staff Request Queue (200 OK)

​Success: Reply Posted (201 Created)

​Success: Ticket Resolved (200 OK)

​6. Error Responses

​7. Security Considerations

​8. Token Usage

​9. Token Refresh

​10. Logout / Session Invalidation

​11. Usage Example (cURL)

​12. Notes / Special Behaviors

1. API Purpose

2. Endpoint Definition

3. Authentication Flow

4. Request Structure

POST /parent-app/write-to

GET /parent-app/write-to

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

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

GET /teachers-app/write-to

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

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

5. Response Structure

Success: Request Submitted (201 Created)

Success: Parent Request List (200 OK)

Success: Full Thread View (200 OK)

Success: Staff Request Queue (200 OK)

Success: Reply Posted (201 Created)

Success: Ticket Resolved (200 OK)

6. Error Responses

7. Security Considerations

8. Token Usage

9. Token Refresh

10. Logout / Session Invalidation

11. Usage Example (cURL)

12. Notes / Special Behaviors