Urgent: Unresolved 500 Errors on POST /api/medical/students/{schoolId}/documents + Critical Documentation Gaps

Dear iSAMS Support Team,

We urgently require assistance resolving persistent 500 errors when using the POST /api/medical/students/{schoolId}/documents endpoint, despite following the "Try It" example and validating all parameters against live system data. Below is our detailed analysis:

1. Current Issue

Request:

curl -X POST \--header "Authorization: Bearer [VALID_TOKEN]" \--header "Content-Type: multipart/form-data" \-F "data={\"categoryId\":2,\"documentSourceId\":1,\"name\":\"Test2\",\"sensitivity\":0,\"description\":\"Test\"};type=application/json" \-F "file=@Test.pdf;type=application/pdf" \
https://[DOMAIN]/Main/api/medical/students/0030285331/documents

Response:

HTTP/1.1 500 Internal Server Error  x-request-tag: 05b9f2d8-dea2-404b-a1b3-5c5023b0954b  

Validation:

• ✅ categoryId=2 & documentSourceId=1 confirmed valid via existing medical documents

• ✅ Student ID 0030285331 exists (verified via GET /api/students)

• ✅ PDF file <2MB, non-corrupted, matches application/pdf MIME type

• ✅ Bearer token works for GET requests

2. Critical Documentation Gaps

A. Multipart/Form-Data Requirements

The "Try It" example uses URL-encoded JSON (%7B...%7D), but documentation lacks:

• Whether URL-encoding is required vs. raw JSON

• Required Content-Type for the data part (e.g., text/plain vs. application/json)

• Whether filename is allowed in the file part's Content-Disposition

B. Field Validation Rules

No guidance on:

• Valid categoryId values (we use 2 "Medical Notes" successfully in other entries)

• Meaning of documentSourceId=1 ("Medical Module")

• name field constraints (special characters, max length)

C. Error Responses

• 500 errors return empty bodies, making debugging impossible

• No examples of 400/500 payloads (e.g., invalid file type, missing fields)

D. Working Examples

Lack of:

• Raw HTTP request examples with boundaries

• Postman/Insomnia collections

• .NET/Python code samples

3. Steps to Reproduce

1. Use the exact "Try It" CURL command with:

   • Valid student ID

   • Valid Bearer token

   • PDF file matching existing working documents

2. Observe 500 error with no error details

4. Requested Improvements

Immediate:

• Share server logs for request tag 05b9f2d8-dea2-404b-a1b3-5c5023b0954b

• Confirm if data field requires URL-encoding

Documentation:

POST /Main/api/medical/students/083613705547/documents HTTP/1.1  
Content-Type: multipart/form-data; boundary=boundary_123  Authorization: Bearer [token]  

--boundary_123  
Content-Disposition: form-data; name="data"  Content-Type: application/json  

{"categoryId":2,"documentSourceId":1,"name":"Epipen Plan","sensitivity":0}  

--boundary_123  
Content-Disposition: form-data; name="file"; filename="action_plan.pdf"  Content-Type: application/pdf  

[PDF bytes]  
--boundary_123--

Error Examples:

json

// 400 Example{
  "code": "InvalidCategory",
  "message": "categoryId=5 is invalid. Valid values: [1,2]",
  "documentation": "https://[domain]/api-docs/medical-categories"}

5. Business Impact

This blocks critical medical record updates, forcing manual workarounds that:

• Violate our SLAs for student health updates

• Introduce compliance risks with medical data handling