Skip to content

Export evidence and data

This is Phase 3: pulling data out for downstream activities such as reporting, an inclusion narrative for Ofsted, and audit-grade evidence you can feed into your own funding and audit processes.

The raw material is the support record: every time a learner is supported, Cognassist captures what was done, which reasonable adjustments were applied, and whether the support met the coverage standard. That recording happens in-product; see How Cognassist is used for who does it and where. This guide covers reading that evidence back out, either one learner at a time or the whole cohort in one export.

Every record preserves the golden thread: the support links back through its reasonable adjustment to the assessed cognitive barrier it addresses, which is what makes the evidence audit-grade. Cognassist supplies that evidence; it does not submit anything to the DfE or anyone else on your behalf, so how you use it stays your decision under your own eligibility and quality policy.

Read one learner's records

Reach for this when you want to surface a specific learner's evidence in your own system, or reconcile what you already hold.

GET /v1/learners/{learnerId}/supportrecords returns a paginated summary, most recent first. Supply lastUpdatedSince (YYYY-MM-DD) to fetch only what changed since your last sync.

curl "https://api.uk.cognassist.com/v1/learners/{learnerId}/supportrecords?pageSize=25&pageIndex=1&lastUpdatedSince=2026-04-01" \
  -H "Authorization: Bearer <token>"

GET /v1/learners/{learnerId}/supportrecords/{supportRecordId} returns the full record: the free-text narrative, the reasonable adjustments applied, the modules selected, and the coverage assessment against the three I's (Intent, Implementation, Impact) that closes the golden thread. Records are either type 10 Regular or type 20 Above and beyond. For the full response schema and every code, see the API reference.

The API today exposes the reasonable-adjustment evidence captured in support records. Exposing the structured support plan as first-class, queryable objects, plus webhook events for plan and review changes, is planned rather than live today. See the Roadmap.

Export the whole cohort

To pull every learner's evidence in one payload, use the bulk export. It is asynchronous: you do not get the data on the request that starts it. You ask for the export, Cognassist builds it in the background, and the finished data arrives on a webhook, not on the response to your request.

Because the payload arrives by webhook, subscribe before you call the export. If no live Learner Export Completed subscription exists when the export finishes, the data has nowhere to go and you will never receive it.

Subscribe to the webhook first

The POST /v1/learnerexports response only confirms the request was accepted. The data itself is delivered by webhook, so subscribe to Learner Export Completed before you start an export.

The flow is three steps:

  1. Subscribe a webhook to Learner Export Completed (and Learner Export Failed, so you hear about failures). Do this first; see Webhooks.
  2. Call POST /v1/learnerexports with a date range. You get back a requestId.
  3. Cognassist sends a 700 Learner Export Completed webhook carrying that same requestId and the full evidence payload. On failure you get an 800 Learner Export Failed webhook against the same requestId.
sequenceDiagram
    participant You as Your system
    participant API as Cognassist API
    participant Hook as Your webhook endpoint
    Note over You,Hook: Step 1 happens once, before you ever call the export
    You->>API: Subscribe to 700 and 800 (POST /v1/webhooks)
    You->>API: POST /v1/learnerexports (date range)
    API-->>You: 202 Accepted with a requestId
    Note over API: Cognassist builds the export in the background
    API->>Hook: 700 Learner Export Completed (same requestId, full payload)
    Note right of Hook: On failure, 800 Learner Export Failed arrives instead
The request and the immediate response 
curl -X POST "https://api.uk.cognassist.com/v1/learnerexports" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "exportFromDate": "2026-04-01", "exportToDate": "2026-04-30" }'

The response confirms acceptance and returns the requestId you match the webhook against:

{ "requestId": "00000000-0000-0000-0000-000000000000" }

The 700 payload carries the requestId (match it to your request) and an ExportData array, one entry per evidence record. The full field list, the code tables, and a worked example live once in the Learner Export Completed (700) payload reference; the API reference carries the schema. Cognassist retries deliveries, so an export can arrive more than once: deduplicate on the envelope's DataId, as described in Webhooks: delivery, retries and security.

How large a range can I request?

No maximum date range or payload size is published for the bulk export. Rather than guess a limit, design for the async model: ask for the range you need, then react to whichever webhook arrives.

  • If the export succeeds, you get the 700 Learner Export Completed webhook with the payload.
  • If it does not, you get the 800 Learner Export Failed webhook against the same requestId, so a failure is a signal you can act on, not silence. Log it and re-request if appropriate. See Troubleshooting for handling an 800.

To keep the finished payload manageable in your downstream system, a practical pattern is to export in bounded windows (for example month by month) and reconcile each window on DataId. To move a very large historical estate in one pass, confirm the current limits and the best approach with your Cognassist contact before you build around a single call.

Access scope

Your credentials only ever return your own organisation's learners; see access scope in Core concepts. Your organisation is one Cognassist client with one credential set, so an export spans the whole organisation. See your organisation is a single client in Core concepts.

Where next