Skip to content

Before you start

This is the developer pre-flight for a Cognassist integration: what to gather, the one hard prerequisite that trips most first attempts, and how to know you are ready to build. You can read it cold, with no prior context and no Cognassist meeting.

The concepts behind this, the three phases and the decisions that shape them, live in Planning your integration. This page assumes that shape and gets you to the starting line. Cognassist is UK-hosted SaaS, 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 an inbound channel if you want events pushed to you.

What to gather first

Have these ready before you write anything. Most are things you already hold; a couple are decisions rather than values.

  • [ ] Your organisation name and UKPRN. The UKPRN identifies your provider to Cognassist.
  • [ ] API credentials: a clientId and clientSecret, issued to your organisation. See Get access to request them.
  • [ ] Your identity model: single sign-on or email-based accounts. This is a Phase 1 decision; the trade-off is set out in Planning your integration, with the detail in Single sign-on.
  • [ ] Your delivery model: webhooks (directly or via a low-code receiver) or polling. Keep in sync is the canonical home for that decision.
  • [ ] Tutor accounts already provisioned in the Cognassist app. This is a hard prerequisite, covered next.

Tutors must exist in Cognassist before your first learner

Every learner you create names a primaryTutorEmail, and that email must resolve to a tutor who already exists in Cognassist. There is no API to list or create tutors today, so provision your tutor accounts in the Cognassist web app (or ask your Cognassist contact) before your first create call. This is the single most common thing to trip a first integration, so settle it early. Deciding who owns each learner is covered in Planning your integration.

How learners are matched to your systems

You do not need a national learner number to get started. On create, you supply clientReference, your own id for the learner in your MIS. Always set it: it is the primary key you use to reconcile Cognassist against your systems. Store the learnerId and learnerUserId returned on create and use them on every later call. Join keys and identifiers are defined once, in full, in Core concepts; use that as the canonical reference rather than re-deriving them here.

The one identifier gotcha: there is no native ULN field

There is an optional learnerUniqueReference field, the closest slot to a Unique Learner Number if you want to store one. When supplied it is validated and must be unique within your organisation, but it is optional, so it is not your join: keep clientReference as the primary key you own. Core concepts explains the identifier roles.

You are ready when...

You can answer yes to all four:

  1. You know your UKPRN and have requested API credentials. See Get access.
  2. Your tutor accounts exist in the Cognassist app.
  3. You have picked how data moves (webhooks, with polling as the fallback) and your identity model (single sign-on or email).
  4. You know your organisation is a single client with one credential set, however many sites it spans.

Next steps