Fall risk API

The fall risk API creates an empty result and returns the five relative URLs used by the assessment flow: quiz, sit-to-stand, tandem stance, single-leg stance, and tandem walk.

Create an assessment

POST /api/fall-risk

The route derives the client from the request host, requires the fallRisk module, and authenticates the request through GOFA's existing integration boundary. See User authentication or Client tokens for the credential handoff used by your integration.

The JSON body accepts:

Example:

const response = await fetch("https://your-client.gofa.app/api/fall-risk", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${firebaseIdToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userId: "client-user-id",
    userInfo: { name: "Example User", age: 72, gender: "female" },
    returnUrl: "/assessments/complete",
    skipDeviceSetup: false,
  }),
});

if (!response.ok) throw new Error(`Create failed (${response.status})`);
const flow = await response.json();

The successful response has status 200:

{
  "fallRiskResultId": "result-id",
  "quizUrl": "/fall-risk/result-id/quiz?returnUrl=%2Fassessments%2Fcomplete",
  "sitToStandTestUrl": "/fall-risk/result-id/sit-to-stand?returnUrl=%2Fassessments%2Fcomplete",
  "tandemStanceTestUrl": "/fall-risk/result-id/tandem-stance?returnUrl=%2Fassessments%2Fcomplete",
  "singleLegStanceTestUrl": "/fall-risk/result-id/single-leg-stance?returnUrl=%2Fassessments%2Fcomplete",
  "tandemWalkTestUrl": "/fall-risk/result-id/tandem-walk?returnUrl=%2Fassessments%2Fcomplete",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "returnUrl": "/assessments/complete"
}

The returned paths are /fall-risk/... paths. They are the launch routes for the deployed API contract; do not substitute an internal fall-risk-v2 path. Add the noAutoNav=true query parameter to an individual page when the host application will control the next step and navigation. If the returned URL already has a query string such as returnUrl, add the parameter with a URL builder so the existing parameters are preserved. The iframe event guides below describe the callbacks for each step.

When userId is omitted, the route uses the authenticated token UID when one is available; otherwise the new record has no explicit user association. Do not put the request credential in logs or URLs.

Some SilverCare handoffs can return 402 with a membership-required response when the client, origin, and account meet the product's membership gate. Keep the host application responsible for displaying that plan handoff.

Iframe events

Each test page sends a source, type, and payload envelope to its parent window. See the individual guides for the current event names and payloads:

• Quiz events
• Sit-to-stand events
• Single-leg stance events
• Tandem stance events
• Tandem walk events

Always validate both event.origin and event.source before handling a message. The current pages post with a wildcard target origin for compatibility; the receiver remains responsible for narrowing the sender.