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.

When learnerStatus flags a learner as Consider a needs assessment, GET /v1/learners/{learnerId}/supportplan/needsassessmentdecision returns whether that stage-gate decision has been made. See Read the support plan for the field shapes and the report-less behaviour.

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 whole PDF, covering relative strengths, speed of working, and the CogType label, 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, delivers the full narrative as the PDF, and exposes the agreed support plan through the endpoints below.

Read the support plan

The support plan is the agreed set of adjustments and goals a tutor puts in place with a learner after the assessment. Where the result above is the assessment output, the support plan is what the organisation decided to do about it. Reach for these when you want to surface the agreed plan in your own system rather than the narrative PDF. Each is a GET under /v1/learners/{learnerId}/supportplan/, and each returns one section of the plan:

  • /barriers: the barriers assigned to the learner, each with its name, category, and description, plus any free-text custom barriers.
  • /reasonableadjustments: the agreed adjustments, split into those derived from the learner's cognitive domains (domainAdjustments) and those derived from their barriers (barrierAdjustments). Each carries a title, an implementation worked example, and the domains or barriers it addresses. Each entry in a domain adjustment's domains carries an id, the same cognitive-domain code returned by the assessment result's domainId, so decode it with the domain codes in Core concepts. A barrier adjustment's own id is stable across changes to the plan and is the same identifier you see for that adjustment on a support record, so you can correlate the two.
  • /goalsandimpact: the course demands the plan responds to, and the impact if the support is not met.
  • /reviewcadence: how often the plan is reviewed (weeks), and the learner's sharing consent per recipient. Each consent entry carries a recipient object whose id is an integer code (1 = end-point assessment or awarding body, 2 = client, 4 = employer), so decode the code rather than depending on a label; see the API reference for the enum.
  • /needsassessmentdecision: after a learner is flagged Consider a needs assessment, the Evaluate stage-gate decision on whether they proceed to a full needs assessment: proceedToNeedsAssessment (nullable, null until a decision is recorded), the evidence rationale behind it, and courseDetails (the learner's job role, null when none is recorded).
  • /signatures: who has signed off the agreed plan, and when. Reach for it when you need to evidence that a plan was agreed rather than merely recorded. agreementKind.id says what was signed: the plan first agreed after the needs assessment (10), or the outcome of a progress review that continued (20) or ended (30) the support. A review agrees a fresh plan rather than editing the previous one, so this endpoint always describes the current agreement and the signatures given for it; the kind belongs to that agreement, so it is the same for every entry in signatures rather than varying by signatory. signatureStatus.id is the overall state (10 unsigned, 20 partially signed, 30 fully signed); a support-plan agreement requires both the tutor and the learner, so 20 means exactly one of the two has signed. Each entry in signatures carries the signatory's role.id (10 tutor, 20 learner), their userId, their name (null when the person's account can no longer be resolved, while the rest of the entry stays accurate), signedAtUtc, and the method.id they signed by (10 typed, 20 uploaded), oldest first. Invalidated signatures are left out, so the list matches the status, and the signature images themselves are never returned. The status and the list are read separately, so a signature captured or invalidated part-way through your request can land in one and not the other. Re-read rather than treating a momentary mismatch as a data error. See the API reference for the enums.

Three behaviours change how you call these:

  • The plan is the agreed set, not the full catalogue. reasonableadjustments returns only the adjustments actually agreed for the learner, not every adjustment that could apply. This is the agreed plan itself, distinct from the per-session evidence you read on support records, and it sits on the same golden thread: every agreed adjustment traces back to an assessed barrier.
  • A learner may not have a plan yet. goalsandimpact and reviewcadence return 404 when the learner has no support plan, so treat a 404 as "no plan agreed yet", not an error to retry. barriers and reasonableadjustments return empty arrays in the same state. needsassessmentdecision instead returns 200 with proceedToNeedsAssessment and evidence both null and courseDetails still populated, because the job role does not depend on a support plan.
  • On signatures, "nothing to sign" and "not signed yet" are different answers. It returns 404 when the learner has no support-plan agreement to sign at all, and 200 with signatureStatus.id 10 and an empty signatures array when the agreement exists but nobody has signed it. Only the second is chaseable, so keep the two apart rather than collapsing both to "no signatures".

For the exact response shape of each section, see the API reference.

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