Integration checklist

This is the single, ordered runbook for a Cognassist integration: every step, in the order you do it, each linking to the guide that covers it in depth. Work top to bottom and you will have learners assessed, results flowing into your systems, and evidence you can export for your own funding and audit processes. Other pages go deep on one topic each and link back here for the sequence, so if you lose the thread, this is the page to return to.

Cognassist is UK-hosted SaaS, so there is nothing to install. An integration is a set of outbound calls from your systems to https://api.uk.cognassist.com, plus one inbound endpoint on your side to receive events. The shape is: get access, put learners in, subscribe to the events you care about, trigger the assessment, then pull results and evidence back out.

Two parts of the flow are asynchronous: the assessment result and the bulk evidence export. You start each with one call and the answer arrives later, delivered to your webhook. This is why webhooks come first and why the order below is load-bearing.

Subscribe before you trigger

Create your webhook subscription before you send an assessment invite or call POST /v1/learnerexports. Trigger first and subscribe second, and the event fires before your endpoint exists to receive it. This is the most common integration mistake, and doing step 6 ahead of steps 7 and 11 avoids it entirely.

The runbook

Follow these in order. Steps 1 to 5 stand up the minimum integration; steps 6 to 10 put results where decisions are made; step 11 pulls evidence out.

1. Request credentials. Ask your Cognassist contact for a clientId and clientSecret scoped to your organisation, and agree how you will test safely first. See Get access.
2. Authenticate and cache the token. Exchange your credentials at POST /v1/auth for a short-lived bearer token, cache it, and reuse it until it nears expiry rather than re-authenticating per call. See Getting started.
3. Confirm your tutors exist. Every learner needs a primaryTutorEmail, and it must resolve to a tutor already provisioned in the Cognassist app. There is no API to create tutors, so line this up before your first create call. See Create and manage learners.
4. Decide identity and delivery. Settle the planning decisions: single sign-on or email accounts, invite email or embedded assessment URL, and who owns each learner. See Planning your integration.
5. Create and reconcile learners. Create each learner with POST /v1/learners, and store the returned learnerId and learnerUserId against your own record. The reconcile recipe, and the join keys behind it, live in Create and manage learners and Core concepts.
6. Subscribe your webhooks, before you trigger anything. Register your endpoint with POST /v1/webhooks for the events you care about, and verify the signature on delivery. Do this ahead of steps 7 and 11. See Webhooks.
7. Invite or embed the assessment. Send Cognassist's branded invite with POST /v1/learners/{learnerId}/assessment/invite, or embed the link from GET /v1/learners/{learnerId}/assessment/url in your own journey. See Send the assessment.
8. Receive Assessment Completed. When a learner finishes, Cognassist delivers the Assessment Completed webhook (event 100) to the endpoint you subscribed in step 6. React to it instead of polling. See Keep in sync.
9. Fetch the result. On that event, call GET /v1/learners/{learnerId}/assessment to pull the learner's cognitive profile, classification, and support-likelihood signal. See Retrieve and render results.
10. Render it responsibly. Display the profile as a signal, not a diagnosis: lead with strengths, decode the status and rating for your users, and treat support as offered rather than imposed. See Retrieve and render results.
11. Export evidence. For reporting and audit, subscribe to Learner Export Completed (event 700) first, then call POST /v1/learnerexports over a date range. The per-learner evidence payload arrives on that webhook, preserving the golden thread from support delivered back to the assessed need. See Export evidence and data.

Steps 1 to 10 already deliver assessed learners and results in your systems; the export in step 11 layers on for reporting. You do not have to build the whole runbook before any of it is useful.

Where each step fits

The runbook maps onto the three phases from Planning your integration:

Phase	Steps	Outcome
1. Get started	1 to 5	Learners exist and are ready to assess
2. Put the data where it is needed	6 to 10	Results reach the people and tools that act on them
3. Pull data out	11	Evidence for your own funding and audit processes

If you cannot receive inbound HTTPS (polling fallback)

Webhooks are the primary pattern, and steps 6, 8 and 11 assume you can receive an inbound HTTPS request. If nothing in your estate can accept one, you have two options rather than a different runbook:

• Bridge the webhook. A low-code receiver such as Power Automate's "When a HTTP request is received" trigger, or Logic Apps, can accept the webhook in the cloud and write into your on-prem system through whatever route it already exposes. This is a helper for receiving webhooks, not a separate integration method. See Automate with low-code.
• Poll as a fallback. Where webhooks genuinely cannot be received, replace steps 8 and 11 with a scheduled, incremental poll of the API. This trades immediacy for reach; the recipe and the rate-limit trade-off are in Keep in sync.

Getting learners in has a further fallback: a one-way SFTP push. It carries learners into Cognassist only, does not read any data back out, and is not available for everything, so treat it as a limited channel for step 5 when neither the API nor a low-code bridge is possible. See SFTP learner upload.

What is not on this list

This runbook covers what is live today. Structured support-plan and reasonable-adjustment data, plan and review webhook events, tutor-account endpoints (creating or listing staff), and a queryable Insights API are not part of the current API. Location (making sites within an organisation first-class) is planned rather than live. See the Roadmap for what is planned, and Core concepts for how your organisation maps to one client.

Related

• Getting started: authenticate and run the first calls.
• Planning your integration: the decisions behind steps 4 and 5.
• Webhooks: the delivery model, the eight live events, and signature verification.
• Keep in sync: webhooks against polling, and the reconcile that backs them up.
• API reference: try every endpoint live, with the full request and response schema for each field and enum.