Assessments
Create a cognitive screening flow and read or update its client-scoped result.
The cognitive assessment API creates an empty screening result and returns the URLs for each user-facing step. The flow covers basic information, memory recall, verbal fluency, orientation, delayed recall, and a results view.
POST /api/cognitive-assessment
The route derives the client from the request host, requires the
cognitiveAssessment module, and uses GOFA's authenticated integration
boundary. See User authentication
or Client tokens for the
credential handoff used by your integration.
The JSON body accepts:
| Field | Type | Description |
|---|---|---|
userId | string, optional | Existing client user to associate with the result. The route verifies the user for the client. |
email | string, optional | Email snapshot. Invalid values return 400. |
photoURL | string, optional | Valid URL snapshot. Invalid values return 400. |
userInfo | object, optional | Validated assessment user information snapshot. Invalid snapshots are ignored. |
returnUrl | string, optional | Relative path beginning with /; protocol-relative paths such as //host are rejected. |
resultMode | direct or qr, optional | Selects the supported entry mode. It may also be supplied as a query parameter. |
origin | string, optional | Trimmed source label retained with the result. |
Example:
const response = await fetch("https://your-client.gofa.app/api/cognitive-assessment", {
method: "POST",
headers: {
Authorization: `Bearer ${firebaseIdToken}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
userId: "client-user-id",
userInfo: { name: "Example User", age: 72 },
returnUrl: "/assessments/complete",
resultMode: "direct",
}),
});
if (!response.ok) throw new Error(`Create failed (${response.status})`);
const flow = await response.json();The successful response has status 200:
{
"cognitiveAssessmentResultId": "result-id",
"basicInfoUrl": "/cognitive-assessment/result-id/basic-info?returnUrl=%2Fassessments%2Fcomplete&resultMode=direct",
"memoryRecallUrl": "/cognitive-assessment/result-id/memory-recall?returnUrl=%2Fassessments%2Fcomplete&resultMode=direct",
"verbalFluencyUrl": "/cognitive-assessment/result-id/verbal-fluency?returnUrl=%2Fassessments%2Fcomplete&resultMode=direct",
"orientationUrl": "/cognitive-assessment/result-id/orientation?returnUrl=%2Fassessments%2Fcomplete&resultMode=direct",
"delayedRecallUrl": "/cognitive-assessment/result-id/delayed-recall?returnUrl=%2Fassessments%2Fcomplete&resultMode=direct",
"resultsUrl": "/cognitive-assessment/result-id/results?returnUrl=%2Fassessments%2Fcomplete&resultMode=direct",
"createdAt": "2026-01-01T00:00:00.000Z",
"returnUrl": "/assessments/complete",
"resultMode": "direct"
}When userId is omitted, the deployed route creates or reuses a client-scoped
anonymous Firebase identity and may return firebaseCustomToken for the flow.
Treat that value as a credential: keep it out of logs and URLs, and pass it only
to the intended Firebase sign-in handoff.
Use the returned resultsUrl for the user-facing results page. The API routes
for an integration are:
| Method | Route | Purpose |
|---|---|---|
GET | /api/cognitive-assessment-results | List results for the authenticated client or user. Supports userId and limit; an explicit clientId is reserved for an authorized GOFA super-admin context. |
GET | /api/cognitive-assessment-results/{id} | Retrieve one result and its step/result URLs. |
PATCH | /api/cognitive-assessment-results/{id} | Save an allowed partial update for one result. |
List responses use { "data": [...], "count": number }. A single-result
response uses { "data": result, ...urls }. The result is always checked
against the request's client boundary.
The update route is strict: unknown keys and the immutable id, clientId, and
createdAt fields are rejected. Send assessment progress fields from the flow;
treat user association, linked-client, assessor, and other ownership metadata
as server-managed. A typical progress update is:
{
"status": "completed",
"scores": {
"rawTotal": 24,
"adjustedTotal": 25
}
}When status is completed, the route records completedAt. Keep the nested
assessment data and score fields produced by the flow together; a partial
update can replace a nested object according to the deployed update schema.
The persisted result can include these domain scores:
| Domain | Maximum |
|---|---|
| Memory | 5 |
| Verbal fluency | 9 |
| Orientation | 6 |
| Delayed memory | 10 |
| Raw or adjusted total | 30 |
The result may also include a quick-screen recommendation, percentile risk
band, domain details, interpretation, and riskLevel. These are assessment
outputs; do not infer a diagnosis or substitute them for clinical judgment.
Public integration boundary
The public flow covers creating a screening, collecting its user-facing steps, and reading or saving its result. B2B player history, kiosk administration, bulk management, and other operator workflows are intentionally excluded from this reference.