Fall Events API

Endpoints for reporting and retrieving fall events.

POST /falls

Report a fall event.

Method: POST Auth Required: Yes Rate Limit: Unlimited

Request Body

Field	Type	Required	Description
confidence	float	Yes	Confidence level (0-1)
location	string	No	Where fall occurred
witnessed	boolean	No	Was it witnessed
injuries	string	No	Description of injuries

Example Request

curl -X POST http://localhost:3000/api/falls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "confidence": 0.85,
    "location": "bedroom",
    "witnessed": false,
    "injuries": "Minor scrape on left knee"
  }'

Success Response

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": "fall-uuid",
    "userId": "user-uuid",
    "confidence": 0.85,
    "status": "HIGH",
    "location": "bedroom",
    "witnessed": false,
    "createdAt": "2026-03-18T10:30:00Z",
    "alerts": {
      "notified": true,
      "caregiverCount": 2
    }
  }
}

---

GET /falls

Get user's fall events.

Method: GET Auth Required: Yes Pagination: Yes

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	10	Results per page
status	string	-	Filter (NO_FALL, SUSPICIOUS, POTENTIAL, HIGH, CONFIRMED)
days	integer	30	Last N days

Example Request

curl http://localhost:3000/api/falls?status=HIGH&days=7 \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response

HTTP/1.1 200 OK
{
  "success": true,
  "data": [
    {
      "id": "fall-uuid",
      "confidence": 0.85,
      "status": "HIGH",
      "location": "bedroom",
      "createdAt": "2026-03-18T10:30:00Z",
      "responded": true,
      "responseTime": 180
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "totalPages": 1
  }
}

---

GET /falls/recent

Get recent falls across all patients (caregiver/admin).

Method: GET Auth Required: Yes Permissions: Caregiver, Admin Pagination: Yes

Query Parameters

Parameter	Type	Default	Description
hours	integer	24	Last N hours
limit	integer	20	Results per page

Example Request

curl http://localhost:3000/api/falls/recent?hours=24 \
  -H "Authorization: Bearer CAREGIVER_TOKEN"

---

GET /falls/:id

Get specific fall details.

Method: GET Auth Required: Yes Permissions: Event owner, assigned caregiver, or admin

Example Request

curl http://localhost:3000/api/falls/fall-uuid \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response

HTTP/1.1 200 OK
{
  "success": true,
  "data": {
    "id": "fall-uuid",
    "userId": "user-uuid",
    "deviceId": "device-uuid",
    "confidence": 0.85,
    "status": "HIGH",
    "location": "bedroom",
    "witnessed": false,
    "injuries": "Minor scrape on left knee",
    "sensorData": {
      "accel": [0.5, 0.3, 9.8],
      "gyro": [0.1, 0.2, -0.05],
      "timestamp": "2026-03-18T10:30:00Z"
    },
    "alerts": [
      {
        "caregiverId": "caregiver-uuid",
        "sent": true,
        "acknowledged": true,
        "timestamp": "2026-03-18T10:30:15Z"
      }
    ],
    "createdAt": "2026-03-18T10:30:00Z"
  }
}

---

Fall Confidence Levels

Level	Range	Description	Action
NO_FALL	0.00 - 0.30	No fall detected	None
SUSPICIOUS	0.31 - 0.50	Possible fall	Log event
POTENTIAL	0.51 - 0.70	Likely fall	Alert caregiver
HIGH	0.71 - 0.89	Strong indicators	Notify + alert
CONFIRMED	0.90 - 1.00	Definite fall	Emergency protocol

---

Related Documentation

• IoT Pipeline
• Fall Detection
• API Reference