Planning your integration¶

This page gives you the mental model to plan a Cognassist integration before you write any code. Cognassist is a UK-hosted SaaS platform, so there is nothing to install: an integration is a set of outbound calls from your systems to the API at https://api.uk.cognassist.com, plus webhooks Cognassist sends back to you. It works in three phases, and Phase 1 delivers value on its own.

For a code-light overview of what this touches and why the approach is sound, see For decision makers. When you are ready to build, this page gives you the shape and the Integration checklist gives you the step-by-step order. Terms and join keys are defined once in Core concepts.

The three phases¶

Phase	Goal	What it delivers
1. Get started	Stand up the minimum integration	Learners get assessed and the right people see the results
2. Put the data where it's needed	Surface results to the people and systems that make decisions	Tutors act on profiles inside the tools they already use
3. Pull data out	Reporting and evidence for downstream processes	Evidence you can feed into your own funding and audit processes

Ship Phase 1 first. Phases 2 and 3 layer on once learners are flowing.

Phase 1 is three decisions¶

The minimum viable integration is three decisions. Settle these and learners get assessed and the right people see results; everything else is an enhancement.

Decide how people sign in to the Cognassist web platform: either enable single sign-on so they use your existing directory, or rely on email-based accounts. Single sign-on is all-or-nothing: when it is on it applies to everyone who signs in, staff and learners alike, so turning it on requires every learner to already exist in your identity provider. Where staff are in your directory but your learners are not, a common pattern is to keep everyone on email-based accounts and reserve single sign-on for a staff-only tenant. Pick the model that covers everyone before you build. Single sign-on is the canonical reference for the detail.

This is a sign-in decision for people. It is separate from API authentication, which always uses OAuth 2.0 client credentials regardless of how people sign in. See Getting started.

2. How learners reach the assessment¶

Choose one of two live delivery paths, then see Send the assessment for the request and response detail.

API invite email sends Cognassist's own branded invitation. Simplest to adopt, so use this unless you want the assessment inside your own journey. The invite endpoint blocks repeat sends to the same learner within three days.
Embedded assessment URL returns a link you present inside your own learner-facing tools.

3. Tutor assignment: who owns the learner¶

Every learner needs an owner. The primary tutor is the primary Cognassist user, the person who reviews the profile and records the evidence of support. Who that is is a customer decision: typically pastoral staff for lower-need learners, and ALS or learning-support staff for more complex ones. You set it with primaryTutorEmail when you create the learner. Assignment also governs visibility, which is defined once in Core concepts.

Provision tutors before your first create call

primaryTutorEmail must resolve to a tutor who already exists in Cognassist. There is no API to list or create tutors, so provisioning your staff accounts is a prerequisite the integration does not do for you. Confirm your tutors exist before you start creating learners. See Create and manage learners.

Solving these three unblocks usage. Phases 2 and 3 build on top.

Deciding how data flows¶

Phases 2 and 3 both depend on how your systems and Cognassist exchange changes, so settle the delivery model once, up front. The preference is webhooks first, a low-code receiver such as Power Automate or Logic Apps if you cannot host an inbound endpoint yourself (a helper that receives webhooks, not a separate way to integrate), and polling only as a fallback when you genuinely cannot receive an inbound request.

Keep in sync is the canonical home for this decision and carries the full reasoning: the channel-choice flowchart, the low-code receiver pattern, the polling recipe, and where SFTP fits as a limited, one-way-in fallback for getting learners in. Follow the delivery model you pick there; the sections below assume it.

Your organisation is a single client: one integration against one credential set for the whole organisation.

Phases 2 and 3, in brief¶

Once Phase 1 is live and learners are flowing, the later phases layer on. Both use the delivery model you chose above.

Phase 2 puts the data where it's needed. Pull each profile into your ILP or e-portfolio so a tutor never has to swivel between systems, and keep it current as results arrive. See Retrieve and render results and Keep in sync.
Phase 3 pulls data out in bulk. A single asynchronous export delivers the full per-learner support payload for reporting and evidence. Each record preserves the golden thread from support delivered back to the assessed barrier, which is what makes it evidence you can feed into your own funding and audit processes. See Export evidence and data.

Exposing agreed reasonable adjustments as structured data, and class-level profiles grouped by Tags, are planned, not live today. See the Roadmap.

What to do next¶

You now have the shape: three phases, three Phase 1 decisions, and a webhooks-first delivery model with polling as the fallback. For the exact order to build in, from requesting credentials to exporting evidence, follow the single runbook. It links each step to its guide and flags the one ordering rule that trips people up.

Go to the integration checklist

For the full request and response schema of any endpoint mentioned here, see the API reference.