API Reference
Digital Skills Assessment API
Version 1.0.0 · Base URL https://www.digitalskillsassessment.co.uk/api/v1
Public REST API for e-portfolio and MIS platforms (Aptem, OneFile, Maytas, Bud, PICS, Smart Assessor and others) to consume assessment results from Digital Skills Assessment.
Integration shape: your platform is the API client. An organisation admin generates an Access Key ID and Secret Access Key in DSA (Organisation Settings), and pastes them into your platform's integration configuration — the same shape used by the incumbent assessment APIs this market already integrates with. No OAuth2.
Polling: results are designed for cheap, frequent, incremental polling (per-minute is fine). Use since/cursor pagination and If-None-Match to receive 304 Not Modified on unchanged polls. Rate limits are per key: 300 requests/minute, with 429 + Retry-After when exceeded.
Funding fields: rqf_level places the learner's current skills level within the RQF level descriptors (ASF funding rules 2026/27 §2.5) and below_level_1 evidences the digital entitlement eligibility gate. Both are first-class response fields.
PII: National Insurance numbers are not stored and never returned. Filter by opaque IDs and your own learner references only — no PII in URLs.
Sandbox: a sandbox environment with seeded fake learners and results is available on request — contact admin@digitalskillsassessment.co.uk.
This reference is generated from the machine-readable OpenAPI 3.1 specification. For a guided start, see the developer overview; for the buyer-facing picture, see integrations.
Authentication
Every request carries two headers, generated by an organisation admin in Organisation → Data & API:
X-Access-Key-IdX-Secret-Access-Key
Endpoints
get/health
Connectivity test
Verifies credentials. Point your platform's 'Test Connection' button here.
Responses
200Credentials valid401Invalid credentials
get/assessments
Incremental assessment results (the critical endpoint)
Parameters
| Name | In | Type | Description |
|---|---|---|---|
since | query | string (date-time) | Return results at or after this updated-at position. Amended results are re-fetched. |
cursor | query | string | Opaque cursor from the previous page's pagination.next |
limit | query | integer | |
learner_ref | query | string | Filter to one learner by your own reference |
Responses
200Page of results (ETag supplied for If-None-Match polling)304Unchanged since the supplied If-None-Match ETag429Rate limited — honour Retry-After
get/assessments/{id}
Single assessment with domain breakdown
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) |
Responses
200The assessment404Not 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) |
Responses
200PDF binary404Not found
get/learners
Incremental learner list
Parameters
| Name | In | Type | Description |
|---|---|---|---|
since | query | string (date-time) | |
cursor | query | string | |
limit | query | integer |
Responses
200Distinct learners with last-assessed positions
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.
Request body
application/json · required
| Field | Type | Description |
|---|---|---|
full_namerequired | string | |
email | string (email) | |
ref | string | Your platform's learner reference |
Responses
201Learner provisioned; response includes the assessment URL402Organisation has no assessment credits
get/learners/{ref}
Single learner by your reference, with assessment history
Parameters
| Name | In | Type | Description |
|---|---|---|---|
refrequired | path | string |
Responses
200Learner with assessments404Not found
get/webhooks
List registered webhook endpoints
Responses
200Endpoints (secrets never returned)
post/webhooks
Register a webhook endpoint for push delivery
Deliveries are signed with HMAC-SHA256 over the raw body (X-DSA-Signature), carry X-DSA-Delivery-Id for deduplication, retry with exponential backoff, and dead-letter visibly. The signing secret is returned once.
Request body
application/json · required
| Field | Type | Description |
|---|---|---|
urlrequired | string (uri) | HTTPS endpoint |
Responses
201Registered; response includes the one-time signing secret
delete/webhooks/{id}
Remove a webhook endpoint
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) |
Responses
204Removed404Not found
Schemas
Assessment
| Field | Type | Description |
|---|---|---|
assessment_id | string (uuid) | |
learner | object | |
assessed_at | string (date-time) | |
subject | string: digital | english | maths | |
framework | string | |
rqf_level | string, nullable | Placement within the RQF level descriptors (ASF §2.5) |
rqf_level_code | integer, nullable | ILR PriorLevel code semantics: Entry Level=1, Level 1=2, Level 2=3, Level 3=5 |
below_level_1 | boolean, nullable | ASF digital entitlement eligibility gate |
working_level | string, nullable | |
recommended_next_level | string, nullable | Supports the ASF enrol-above-assessed-level rule |
domains | array of object | |
evidence_pack_url | string | The evidence PDF for this assessment |
report_sha256 | string, nullable | SHA-256 of the evidence PDF, stored at first generation |
Pagination
| Field | Type | Description |
|---|---|---|
limit | integer | |
has_more | boolean | |
next | string, nullable | Absolute URL of the next page; null when exhausted |
Error
| Field | Type | Description |
|---|---|---|
error | object |
A sandbox with seeded learners and results is available on request: admin@digitalskillsassessment.co.uk.