Skip to content

Retrieve and render results

Once a learner completes their assessment, one call returns their cognitive profile, and you put it in front of the people who act on it: the tutor's caseload view, your ILP, your learner record. This is Phase 2 of an integration, put the data where it's needed, and it removes the swivel-seat of re-keying results by hand.

Every call needs a bearer token and uses the base URL https://api.uk.cognassist.com. See Getting started to get one. The codes in the payload decode into the labels a tutor reads; Core concepts is their canonical home, and the full schemas live in the API reference.

Get the assessment result

Pass the learnerId you stored when you created the learner, and you get back a small, flat object whose integers decode into tutor-facing labels.

curl https://api.uk.cognassist.com/v1/learners/{learnerId}/assessment \
  -H "Authorization: Bearer <token>"

A completed result carries a status, a learnerStatus classification, a supportLikelihoodRating, and one entry per cognitive domain in assessmentResults. Read the GET /v1/learners/{learnerId}/assessment schema for the full field list; the decode tables below cover the enums you render from.

A completed result, decoded 
{
  "status": 30,
  "learnerStatus": 20,
  "supportLikelihoodRating": 4,
  "dateAssessmentCompleted": "2026-04-07T09:15:00",
  "assessmentResults": [
    { "domainId": 1, "domainResult": 1 },
    { "domainId": 2, "domainResult": 2 },
    { "domainId": 6, "domainResult": 3 }
  ]
}

This reads: Completed, Monitor and review, one index identified, with the three listed domains resolving to not identified, identified, and insufficient data. Map domainId to a domain name such as Literacy using the domain codes in Core concepts.

Branch on status before reading the rest, because the other fields are only populated once scoring completes.

State Integer What it means What to do
Not completed 20 The learner hasn't finished. Invite or remind them (see Send the assessment).
Awaiting results 10 Finished, but scoring isn't complete yet. Fetch again shortly, or wait for the webhook.
Completed 30 The classification, rating, and results are populated. Render the profile.

All three wire integers (10, 20, 30) are from the LearnerAssessmentStatus enum in the API source. React to completion with the 100 Assessment Completed webhook rather than polling on a timer, so you fetch each result exactly once, the moment it's ready.

Decode the result codes

Three enums decode into the labels a tutor reads: learnerStatus (the headline classification), supportLikelihoodRating (how confident the signal is, where higher is stronger and an index match outranks a domain match), and domainResult (the outcome for each domain). The worked example above shows all three decoded in place. The integer-to-meaning tables live once in Core concepts, their canonical home, with the exhaustive enums in the API reference; keep that open as you build the render rather than copying the values here.

Persist these integers as you receive them, not just the labels you render from them, so you can re-derive display text and reconcile safely later.

Render it responsibly

A cognitive profile is a signal, not a diagnosis

It indicates where support may help; it is never a verdict or a deficit label. Show the whole profile and lead with strengths, present insufficient data as "not enough information" rather than a low score, and frame learnerStatus and supportLikelihoodRating as how likely a learner is to benefit from support the tutor can then offer on an informed basis.

Display the human-readable names, not the raw integers, so a tutor sees "Literacy", not 2. Decode using the result codes and domain codes in Core concepts.

Your credentials only return your own organisation's learners, so a 403 for a learner outside that scope is expected rather than a failure. The access model is described once in Core concepts.

Request the PDF report

The structured result above is the machine-readable profile. For a durable, human-readable companion, and a useful item for your organisation's own evidence pack, request the full PDF report. The call returns 202 Accepted straight away with a requestId, then the finished file is pushed to you by webhook.

curl -X POST https://api.uk.cognassist.com/v1/learners/{learnerId}/assessment/report \
  -H "Authorization: Bearer <token>"

202 Accepted
{ "requestId": "00000000-0000-0000-0000-000000000000" }

The requestId is your correlation handle: hold onto it, then match it against the RequestId in whichever webhook arrives.

  • 200 Assessment Report Created is a multipart/form-data delivery carrying the PDF, plus a data part that echoes your RequestId. The multipart signature check is on the Webhooks page.
  • 300 Assessment Report Request Failed means generation did not complete for that requestId. Log it against the request, surface it rather than silently dropping it, and re-request if appropriate. See Troubleshooting for handling failed deliveries.

The report is generated asynchronously, so the file arrives by webhook rather than on the POST response, following the same 202-then-callback shape as the canonical webhook sequence. The success-or-failure fork it shares with the bulk export is drawn once in Troubleshooting, and both events, their payloads, and signature verification are documented in full on the Webhooks page.

A field-for-field JSON equivalent of the PDF, covering declared barriers, relative strengths, and the personalised reasonable adjustments and goals, is on the roadmap, not available today; you would then be able to render the full report without parsing the PDF. Today the structured API exposes the domains, classification, and support-likelihood above, and the rest is delivered as the PDF.

What to store

Persist the learnerId and the raw result codes you receive, not just their rendered labels, so you can re-derive display text and reconcile later. Keep dateAssessmentCompleted alongside your own records. Your stable cross-system join key stays clientReference, held on your side (see Core concepts).

Where to go next