Skip to content

Getting started

This page takes you from zero to your first assessment result: get credentials, exchange them for a token, create a learner, invite them to their assessment, and read the result back. Every endpoint used here is live today.

The core loop is: you create a learner, that learner completes a short online cognitive assessment in their own time, Cognassist tells you when they finish, you read the result, and you show it to your team. The steps below are that loop in detail.

The Cognassist API is a REST/JSON API. Every request uses HTTPS, sends and receives application/json, and is authorised with an OAuth 2.0 bearer token. The examples lead with curl; if you integrate without writing a service, each step has a Power Automate tab, and the worked example with Power Automate walks the whole flow.

What you need first

Two things come from your Cognassist contact rather than a self-service form:

  • API credentials (a clientId and clientSecret) for your organisation.
  • At least one registered tutor. Creating a learner requires the email of a tutor who already exists in Cognassist, and there is no API to create tutors, so provision your staff accounts first.

See Get access for how to request credentials and what to have ready, and Test safely before you make calls against real learners.

Base URL and versioning

Every endpoint is served from one base URL, and every path carries the API version:

https://api.uk.cognassist.com

The current version is v1. Version v0 is deprecated, so do not build against it. Paths in this guide include the version prefix, for example POST /v1/auth.

This guide shows the flow and the few things the reference does not spell out. For the request and response schema of every endpoint, and every field and enum, the Cognassist API reference is the source of truth. You can try each call live in the Swagger UI, or generate a client from the machine-readable OpenAPI spec at https://api.uk.cognassist.com/swagger/v1/swagger.json.

Authenticate

The API uses the OAuth 2.0 client-credentials grant, a machine-to-machine flow with no user, no browser, and no redirect. You hold a client id and client secret, exchange them for a short-lived access token, and send that token as a bearer credential on every other call. There is no refresh token: when a token nears expiry, request a new one with the same credentials.

POST /v1/auth exchanges your credentials for a token, and it is the only endpoint that does not require a bearer token.

curl -X POST https://api.uk.cognassist.com/v1/auth \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "your-client-id", "clientSecret": "your-client-secret" }'

Use an HTTP action with method POST, URI https://api.uk.cognassist.com/v1/auth, header Content-Type: application/json, and the same JSON body as the curl tab. Parse the response and store accessToken in a variable to reuse across the flow. Full guidance is in the worked example with Power Automate.

The response returns an accessToken and an expiresIn lifetime in seconds. Cache the token and reuse it until it nears expiry, then re-authenticate. Do not call POST /v1/auth per request. Read expiresIn rather than hard-coding the lifetime, and send the token on every other call:

Authorization: Bearer <accessToken>

Treat the client secret like a password

The secret authenticates your organisation and grants access to its learner data. Store it in a secret manager or environment variable, never in source control or client-side code. If it is exposed, contact your Cognassist contact to have it rotated.

API auth is not single sign-on, and what the status codes mean

This flow authenticates a system, not a person. It is independent of single sign-on, which governs how your staff sign in to the Cognassist web platform.

A 401 means the token is missing, malformed, or expired. A 403 means the token is valid but its organisation cannot access that resource. The API reference has the full auth schema and error bodies.

Your first assessment result

The core flow is: create a learner, invite them, and read their result once they finish. Cognassist tells you when the result is ready, so nothing here needs a polling loop:

sequenceDiagram
    participant You as Your system
    participant API as Cognassist API
    participant Learner
    You->>API: POST /v1/learners (create)
    API-->>You: 201 with learnerId and learnerUserId
    You->>API: POST .../assessment/invite
    API-->>You: 202 accepted
    API->>Learner: Assessment invitation email
    Note over Learner: Learner completes the assessment in their own time
    API-->>You: Webhook: Assessment Completed (event 100)
    You->>API: GET .../assessment
    API-->>You: Result to render

The examples below assume you have set $TOKEN to the accessToken from the auth step.

1. Create a learner

POST /v1/learners creates a learner. Three fields carry integration meaning: clientReference is your join key, primaryTutorEmail must already exist in Cognassist, and learnerUniqueReference is an optional secondary reference (validated, but not your join). All three are defined in Core concepts. The snippet below is trimmed to show those keys in context; the full required and optional field list, with validation rules, lives in Create and manage learners and the API reference.

curl -X POST https://api.uk.cognassist.com/v1/learners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientReference": "12345ABCDE",
    "primaryTutorEmail": "tutor.name@example.com",
    "...": "plus the other required fields (see the reference)"
  }'

Use an HTTP action with method POST, URI https://api.uk.cognassist.com/v1/learners, headers Authorization: Bearer @{variables('accessToken')} and Content-Type: application/json, and the same JSON body as the curl tab. Store learnerId from the response for the next actions.

A 201 Created returns two ids: keep both. learnerId is the Cognassist-side key you use on every learner-scoped call, and learnerUserId identifies the learner's user account. The full response schema is in the API reference.

2. Invite the learner

POST /v1/learners/{learnerId}/assessment/invite sends the assessment invitation email. A successful request returns 202 Accepted. You cannot re-invite the same learner within three days; Send the assessment explains that guard and what to do if a learner needs to start sooner.

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

Use an HTTP action with method POST, URI https://api.uk.cognassist.com/v1/learners/@{variables('learnerId')}/assessment/invite, and header Authorization: Bearer @{variables('accessToken')}.

To embed the assessment in your own learner journey instead of emailing an invite, see Send the assessment.

3. Know when it is done, then read the result

A result only exists after a real person completes the assessment. The way to know that has happened is the Assessment Completed webhook (event 100): subscribe to it and Cognassist calls your endpoint the moment a learner finishes. That is the primary pattern, and it means you never sit in a polling loop waiting. See Webhooks for the delivery model and signature verification.

When the event arrives, fetch the result with GET /v1/learners/{learnerId}/assessment:

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

Use an HTTP action with method GET, URI https://api.uk.cognassist.com/v1/learners/@{variables('learnerId')}/assessment, and header Authorization: Bearer @{variables('accessToken')}.

Call it before the learner has finished and it returns a not-completed status rather than a profile. That is expected, not an error.

The response carries the completion status, a three-tier classification, a support-likelihood rating, and a per-domain results array. A cognitive profile is a signal, not a diagnosis: lead with strengths and treat support as offered, not imposed. What each code means is decoded once in Core concepts; how to display a profile responsibly is in Retrieve and render results; the full response schema is in the API reference.

Getting a genuine first result to test with

Because a result only appears once someone completes the assessment, the fastest way to see a real profile come back is to invite yourself or a colleague and complete the assessment, then fetch it. Test safely covers doing this without touching real learners.

Access scope, errors and rate limits

Your credentials are scoped to your organisation, so a 403 Forbidden is expected when you ask for another organisation's learner; Core concepts defines what your credentials can see. There are no published rate limits today, so cache the token, prefer webhooks over polling, and back off on a 429; Troubleshooting covers the error shapes and rate-limit handling.

Next steps