Digital Skills Assessment API

get/health

Connectivity test

Verifies credentials. Point your platform's 'Test Connection' button here.

Responses

• 200Credentials valid
• 401Invalid credentials

get/assessments

Incremental assessment results (the critical endpoint)

Unknown query parameters are rejected with 400 unknown_parameter — a misspelt filter never silently returns the full result set. Filter grammar: CSV within a param is OR, different params are AND. See the top-level description for the delta-safe/delta-unsafe split and the weekly reconciliation requirement.

Parameters

Responses

• 200Page of results (ETag supplied for If-None-Match polling)
• 304Unchanged since the supplied If-None-Match ETag
• 400Invalid or unknown parameter (unknown_parameter, invalid_since, invalid_cursor, invalid_learner_ref, invalid_subject, invalid_assessed_from, invalid_assessed_to, invalid_rqf_level_code, invalid_below_level_1, invalid_status, invalid_group_id, too_many_groups, invalid_sort, sort_with_since)
• 429Rate limited — honour Retry-After

get/assessments/{id}

Single assessment with domain breakdown

Parameters

Responses

• 200The assessment
• 404Not found (also returned for resources belonging to another organisation)

get/assessments/{id}/report.pdf

The evidence artefact (PDF)

Deterministic evidence PDF. X-Report-SHA256 carries the integrity hash stored at first generation.

Parameters

Responses

• 200PDF binary
• 404Not found

get/learners

Incremental learner list

Unknown query parameters are rejected with 400 unknown_parameter; cursors are bound to the query they were minted under.

Parameters

Responses

• 200Distinct learners with last-assessed positions and their active groups (groups[])
• 400Invalid or unknown parameter (unknown_parameter, invalid_since, invalid_cursor)

post/learners

Provision a learner into DSA

Creates an assessment invitation for the learner using the organisation's default test type. Consumes credits exactly as dashboard invitations do; education/unlimited plans bypass credits. The optional groups array is upserted by ref on (type, ref) — no group_id lookup round-trip needed. Missing groups are auto-created (unless the organisation has disabled auto-creation), capped at 500 groups per organisation.

Request body

Responses

• 201Learner provisioned; response includes the assessment URL
• 402Organisation has no assessment credits
• 409group_limit_exceeded — the organisation already has 500 groups
• 422group_autocreate_disabled or team_group_managed

get/learners/{ref}

Single learner by your reference, with assessment history

Parameters

Responses

• 200Learner with assessments
• 404Not found

get/webhooks

List registered webhook endpoints

Responses

• 200Endpoints (secrets never returned)

post/webhooks

Register a webhook endpoint for push delivery

Deliveries carry two HMAC-SHA256 signatures: X-DSA-Signature (legacy, over the raw body) and X-DSA-Signature-256 (recommended, t=<unix seconds>,v1=<hex> where the MAC covers <t>.<raw body> — verify the MAC and reject timestamps outside a 5-minute tolerance to prevent replay). Deliveries also carry X-DSA-Delivery-Id for deduplication, retry with exponential backoff, and dead-letter visibly. The signing secret is returned once. Scoping: omit event_types/group_ids to receive everything — explicit empty arrays are rejected (an empty filter must never silently mean 'deliver nothing'). Event types: assessment.completed (full payload with group_ids), learner.groups.updated (thin payload: {event, learner_ref, added, removed, occurred_at} — re-fetch for details). A subscription scoped by group_ids receives learner.groups.updated when EITHER an added or a removed group matches, so a cohort-scoped subscriber learns of exits.

Request body

Responses

• 201Registered; response includes the one-time signing secret

delete/webhooks/{id}

Remove a webhook endpoint

Parameters

Responses

• 204Removed
• 404Not found

get/groups

List groups

Parameters

Responses

• 200Page of groups
• 400Invalid or unknown parameter

post/groups

Create a group

Idempotent on (type, ref): re-posting an existing group returns it with 200. Groups of type 'team' are managed automatically from the organisation's teams and are rejected with 422.

Request body

Responses

• 200Already existed (idempotent upsert)
• 201Created
• 409group_limit_exceeded
• 422team_group_managed

get/groups/{id}

Group detail with active member count

Parameters

Responses

• 200The group
• 404Not found

patch/groups/{id}

Rename or archive a group

Archive (active=false) rather than delete — membership history is funding-audit evidence and is never destroyed. 'team' groups reject modification (422).

Parameters

Request body

Responses

• 200Updated
• 404Not found
• 422team_group_managed

post/groups/{id}/members

Add members (idempotent)

Adds learners by your own refs. Learners already in the group are reported in already_members, not errored. Membership changes cascade updated_at onto the learners' assessments and emit learner.groups.updated webhook events.

Parameters

Request body

Responses

• 200{ added: [...], already_members: [...] }
• 404Not found

post/groups/{id}/members/remove

Remove members

Removal takes a body (never DELETE /members/{ref}) so learner refs stay out of URLs. Removal is soft — the membership history is retained for point-in-time attribution. Triggers scope-exit tombstones in group_id-filtered delta feeds and learner.groups.updated webhook events.

Parameters

Request body

Responses

• 200{ removed: [...], not_members: [...] }
• 404Not found