Order an assessment from your ATS. Get a score you can defend.

A score on its own is a number. "78th percentile" only means something once you know which version of the test was sat, which form, and which norm group the candidate was compared against. Most assessment APIs return the number and leave the rest in a PDF, or in nobody's hands at all.

Every result this API returns carries scored_against: the test version number, the content hash of that version, the form the candidate actually sat, and the norm group used. The version is pinned to the candidate's assignment at the moment the order is placed, so somebody who starts under one version finishes — and is scored — under that one, however often the catalogue changes underneath them.

That is what makes a result defensible a year later. Norms are refreshed; items are retired and replaced; a test gets a new version. None of that can quietly change what a score you acted on in March meant, because the record of what it was measured against travels with the score itself. If you are ever asked to justify a hiring decision — by a candidate, a regulator or a tribunal — this is the difference between an answer and a shrug.

Where an assessment's norms are still provisional we say so with norms_provisional, and every standardised number comes back null — the raw score stands alone. A percentile derived from an assumed mean asserts a comparison against a group that does not exist, so we do not publish one, here or on the PDF.

Every page a candidate touches while taking an assessment — the hub, the instructions, each question, the submission step and the confirmation — is built to WCAG 2.2 Level AA, and we verify it the way an auditor would: by running axe-core against the real, live pages and requiring zero violations. It is a standing requirement on every change to those templates, not a one-off exercise that produced a PDF once.

One documented exception, because hiding it would be worse than naming it: a timed assessment auto-submits when its countdown ends, with no pause or extend control. That is WCAG's essential exception — the time limit is part of what an ability test measures, and removing it would invalidate the result against the norms the score is compared to. It is standard practice across the industry, and candidates who need extra time get it as an adjustment instead.

This is the part of a public-sector tender most assessment vendors answer with a statement of intent. It is worth asking for evidence — of us as well.

• Timestamps are ISO-8601, UTC, Z-suffixed. Ids are opaque strings — ord_… and res_… — that are not database keys and are not sequential. Store them; do not parse them. So is a listing cursor: it is ours to issue and yours to hand back, not something to construct.
• Rate limits are per key rather than per client, so two of your integrations never starve each other. Over the limit is 429 with a Retry-After header in seconds.
• Reading a result or downloading a report writes a row to our candidate-data access log naming your key's public id. Who looked at a candidate's data has an answer for API reads exactly as it does for a signed-in user.

Errors are always {"code", "detail"}, plus fields when a body failed validation. Branch on code; show detail to a human. Every code, and every field of every endpoint, is in the API reference — and in the OpenAPI document it is rendered from, at /api/v1/openapi.yaml.

{
  "code": "unknown_assessment",
  "detail": "'telepathy' is not an assessment you can order. GET /api/v1/assessments lists the codes available.",
  "fields": {"assessments": ["telepathy"]}
}