Skip to content

Send the assessment

The learner now exists in Cognassist, so the next step is to start their assessment. There are two ways to do it, and you can use both:

  • Send an invitation email and let Cognassist deliver the link and manage the invitation. This is the simplest path and the right default for most integrations.
  • Embed the assessment URL in your own portal or onboarding flow when you want the learner to start without leaving your platform.

This assumes you have already created the learner and hold their learnerId; if not, start with Create and manage learners. Every request needs a bearer token from Getting started. The examples below assume TOKEN holds your access token and LEARNER_ID the learner's id.

The assessment measures a learner's cognitive profile. It is a signal, not a diagnosis: results lead with strengths, and support is offered rather than imposed. Keep that framing in whatever you build around either path. For the vocabulary behind the result, see Core concepts.

Send an invitation email

POST /v1/learners/{learnerId}/assessment/invite sends the invitation email. There is no request body, and a successful call returns 202 Accepted because the email is sent asynchronously.

curl -X POST \
  https://api.uk.cognassist.com/v1/learners/$LEARNER_ID/assessment/invite \
  -H "Authorization: Bearer $TOKEN"

One invite per learner every three days

You cannot re-invite the same learner within three days of a previous invitation. This stops learners being emailed repeatedly and protects Cognassist's sending reputation. If a learner needs to start sooner, hand them the embedded URL instead.

For the full request and response, see the invite endpoint in the API reference.

Embed the assessment URL

GET /v1/learners/{learnerId}/assessment/url returns an assessmentUrl you present to the learner, for example as a button or an embedded frame. This is the pattern e-portfolio and enrolment systems use to keep the learner in a single journey.

curl https://api.uk.cognassist.com/v1/learners/$LEARNER_ID/assessment/url \
  -H "Authorization: Bearer $TOKEN"

Fetch this URL fresh at the moment you need it rather than caching or persisting it. The URL can change, for example when a new invitation email is sent or the assessment is restarted, so a stored one may stop working. For the response shape, see the assessment URL endpoint in the API reference.

Choosing between them

Both paths start the same assessment; they differ only in who delivers the link. Default to the email invite, and reach for the embedded URL when you want the learner to stay inside your platform.

Side-by-side comparison
Invitation email Embedded URL
Endpoint POST .../assessment/invite GET .../assessment/url
Who delivers the link Cognassist emails the learner You render it in your own UI
Best for Learners you reach by email Keeping learners inside your platform
Constraint One invite every three days Fetch fresh; do not store
Success 202 Accepted 200 OK with assessmentUrl

You can use both: embed the URL for learners already in your platform, and fall back to the email invite for the rest.

Handling errors on both paths

The two endpoints have overlapping but distinct 400 cases:

Endpoint Status Cause
Invite 400 Learner has already completed — nothing to invite them to.
Invite 400 Three-day window: a previous invitation was sent within three days.
URL 400 Learner has already completed — no live URL to hand out.
URL 400 Learner has not yet been invited — there is no URL until the first invite is issued.

Check the assessment status before calling either endpoint (see Retrieve and render results), and issue the invite before fetching the URL. For detailed diagnosis of each case, see Troubleshooting.

A 403 Forbidden means the learner is outside your organisation's scope, and a 401 Unauthorized means the bearer token is missing or expired. Access scope and the shared error statuses are defined once in Core concepts and Getting started.

After the learner starts

Completing the assessment takes real time: it is a set of exercises a person works through, not an instant lookup. Build for that gap rather than expecting a result on the next call.

Rather than poll for completion, subscribe to the Assessment Completed event (id 100) and react when the learner finishes. See Webhooks for the delivery model and setup, then Retrieve and render results to read the cognitive profile back and display it responsibly.

Next steps