Skip to content

Keep in sync

Once learners exist in Cognassist, you need a way to keep your own system current as they complete assessments and accumulate support evidence. This guide sets out the recommended way to do that, and the fallbacks for when your estate cannot support it.

It builds on the create-and-reconcile flow in Create and manage learners; read that first for how learners get in and how you match them. All paths are relative to the base URL https://api.uk.cognassist.com and require a bearer token (see Getting started).

Work down this list and stop at the first option your estate can support. Each rung is a fallback for the one above it, not an equal alternative.

  1. Webhooks (recommended). Cognassist POSTs to a URL you own the moment an event fires, so your records update in near real time and you never poll. This is the primary pattern; build for it first.
  2. Webhooks received through a low-code tool. If you cannot expose an inbound HTTPS endpoint from your own service, a low-code receiver (Power Automate, Logic Apps) can accept the webhook for you and write it onward. This is still webhooks; the tool is only the receiver.
  3. Polling (fallback). If you genuinely cannot receive an inbound request at all, call the API on a schedule and pick up what changed. Use this only when both options above are ruled out.
  4. SFTP (partial, one-way in). A scheduled CSV that creates learners in Cognassist. It does not read any data back out, so it is never a complete sync on its own. Reach for it only when your source can emit a file but cannot make or receive API calls.

The first three read data out of Cognassist and keep your system current; SFTP is different in kind, pushing learners in only, so it complements one of the rungs above rather than replacing them.

This page is the canonical home for choosing a channel. Other pages give a one-line lead and link here rather than redraw the decision. How webhook delivery mechanically works lives on the Webhooks page.

flowchart TD
  Q1{Can you receive an inbound HTTPS request?}
  Q1 -- "Yes, from your own service" --> W[Webhooks]
  Q1 -- "Only via a low-code tool" --> WL[Webhooks via Power Automate or Logic Apps]
  Q1 -- "No, not at all" --> P[Polling on a schedule]
  F["File-only source, no API or inbound at all"] --> S[SFTP push, learners in only]

The three branches off the question cover the channels that read data out and keep your system current. The separate SFTP node is the inbound-only complement described below: reach for it only when your source can emit a file but cannot make or receive API calls.

Subscribe with POST /v1/webhooks, giving a url, a secret, and the systemEventIds you want. Cognassist then POSTs to your url each time a subscribed event fires. The events most relevant to keeping records in step are Assessment Completed (pull the learner's result), Modules Assigned (reflect assigned learning), and Learner Export Completed (collect a bulk evidence payload you requested).

The full delivery model, the eight events with their numeric ids, DataId idempotency, signature verification, and the invocation-log audit trail all live on the Webhooks page. Build against that page; this section only places webhooks in the sync decision.

Two properties make webhooks the reliable default:

  • Each change arrives once, on time. You react to a completion when it happens instead of discovering it on the next poll, and you make no wasted calls in the quiet periods between events.
  • You can prove what was delivered. The delivery history is queryable, so a missed or failed POST is visible and you can reconcile just those against the API rather than re-reading everything. See auditing deliveries.

Verify the signature and de-duplicate on DataId before you act

Cognassist retries deliveries, so the same payload can arrive more than once, and any POST to a public URL could be forged. Verify the x-cognassist-sha256 signature and skip any DataId you have already processed before you write anything. Both are covered in full on the Webhooks page.

Webhooks when you cannot host an endpoint

Not being able to expose an inbound HTTPS endpoint from your own systems is common on-premises, but it does not push you to polling. A low-code tool (Power Automate, Logic Apps) can receive the webhook for you and write it onward, so you stay on webhooks. The tool is only the receiver, not a different integration method. Set this up before you consider polling. For the build, see Receive a webhook without writing a service.

Polling (fallback)

Use polling only when you cannot receive an inbound request at all, even through a low-code receiver. Poll on a schedule with targeted, incremental queries rather than re-reading everything.

  • New completions: GET /v1/learners/assessmentcompleted?date=YYYY-MM-DD returns learners who completed on a given date. Run it daily for the previous day, then pull each result with GET /v1/learners/{learnerId}/assessment. The endpoint takes a single date, not a range, so to recover a gap after downtime or a missed run you iterate one call per missed day (bounded, and still gentler than tight polling). If a day is missed entirely, the roster-drift reconcile below is your backstop.
  • Changed evidence: GET /v1/learners/{learnerId}/supportrecords accepts lastUpdatedSince, so you fetch only records updated on or after a timestamp. Store your last run time and pass it next time to pull just the delta.
  • Roster drift: page through GET /v1/learners to refresh your local map, matching rows on email. The full recipe, including why the list matches on email and not clientReference, the stop condition, and the rate-limit trade-off, is in Create and manage learners.
Incremental polling calls 
# Yesterday's completions
curl "https://api.uk.cognassist.com/v1/learners/assessmentcompleted?date=2026-04-06" \
  -H "Authorization: Bearer <token>"

# Support records changed since your last sync
curl "https://api.uk.cognassist.com/v1/learners/00000000-0000-0000-0000-000000000000/supportrecords?lastUpdatedSince=2026-04-06T00:00:00" \
  -H "Authorization: Bearer <token>"

Poll gently: cache the token, and back off on 429 rather than retrying immediately (see Getting started). The exact query parameters and response schemas are in the API reference.

SFTP (partial, one-way in)

To get learners in from a file-only source, a one-way-in SFTP upload is a limited fallback: it never reads data out, so pair it with webhooks or polling for anything you need to keep in sync.

On-premises constraints

On-premises estates (an on-premises MIS in a Microsoft shop) shape which rung you land on, but they do not change the order:

  • If you can stand up any HTTPS receiver, including a low-code flow in your existing Microsoft tenancy, stay on webhooks. That is often achievable even when the system of record itself is on-premises.
  • Only if no inbound request can be received at all should you fall back to polling from a scheduled job that reaches out to the API.
  • SFTP sits alongside either of these for the inbound-learners half, never as the whole integration.

A worked Power Automate example shows a scheduled reconcile as a low-code flow you can copy and adapt.

Additional webhook events for the support plan and review stages (for example plan updated, adjustment changed, review completed) are on the roadmap, not available today; sync coverage today spans assessment, modules, and evidence export.

Your credentials are scoped to your organisation, so every sync path only ever returns your organisation's learners; keeping records in sync never widens who can see a learner's data. Your organisation is a single client, so it all runs against one credential set. See Core concepts for the access model.

Next steps

  • Webhooks: the delivery model, the eight events, DataId idempotency, and signature verification.
  • Create and manage learners: the reconcile loop in full, including why the list matches on email, the stop condition, and the rate-limit trade-off.
  • Automate with low-code tools: receive webhooks or run a poll in a managed flow without writing a service.
  • SFTP learner uploads: the one-way-in file route for getting learners into Cognassist.
  • Export evidence and data: request a bulk evidence payload for your own funding and audit processes.