Fall risk results API

The fall risk result routes read the client-scoped record created by Create an assessment. The result can be partial while the five tests are being completed; derived risk fields are calculated as the available assessment data changes.

List results

GET /api/fall-risk-results

The request must be authenticated and the client's fallRisk module must be enabled. Query parameters:

The response is private and non-cacheable:

{
  "data": [
    {
      "id": "result-id",
      "clientId": "your-client-id",
      "userId": "client-user-id",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "assessmentStatuses": {
        "quiz": "completed"
      },
      "missingAssessments": ["tandemWalk"]
    }
  ],
  "count": 1
}

Retrieve a result

GET /api/fall-risk-results/{fallRiskResultId}

This route uses the fall risk runtime authentication policy and verifies access to the result's client and user. Add ?recalculate=true when a caller with the required access needs the server to refresh derived calculations. A normal response is { "data": result }; the result may also include availableAssessments, missingAssessments, and generated assessment URLs.

The implementation calculates from whichever assessments are available. A record can therefore include:

• quizResults — fall history and risk-factor answers.
• sitToStand — repetition count, five-repetition time, and shoulder tilts.
• singleLegStance — held duration (up to 10 seconds), shoulder tilts, and optional sway series.
• tandemStance — held duration (up to 30 seconds), shoulder tilts, and optional sway series.
• tandemWalk — current round data, successful steps, duration, and swap observations.
• derived riskLevel, frailtyLevel, sarcopeniaRisk, probability calculations, and calculation metadata when enough inputs are available.

The current tandem walk model prefers three rounds, each with a completion flag, completed step count, failure/retry flags, and duration. Older persisted records can still contain deprecated fields. Read the fields present in the response instead of assuming every assessment was completed.

Save a result update

PATCH /api/fall-risk-results/{fallRiskResultId}

Use this route to save an allowed partial update from the assessment flow. The request is strict: unknown fields, ownership changes, and attempts to replace immutable metadata are rejected. The server also checks that the mutation is safe for this assessment record.

{
  "sitToStand": {
    "count": 5,
    "fiveRepsTimeTaken": 14.8,
    "shoulderTilts": [1.2, 1.5, 1.1]
  },
  "assessmentStatuses": {
    "sitToStand": "completed"
  }
}

A successful update returns { "success": true }. Keep user identity, client ownership, timestamps, payment metadata, and derived calculations under the server's control.

Risk bands are product outputs for the assessment workflow. They do not by themselves establish a diagnosis or replace clinical judgment.