Create an assessment

Uploads a paper and turns it into a markable assessment. Use this when the
paper originates in your system: you own it, only your token can see it, and
student hand-ins are marked against it once it is published.

Returns 202 Accepted and starts extraction in the background. Watch for the
assessment.review_ready webhook, or poll the show endpoint.

Parameters

Name	Type	Required	Description
name	string	required	Human-readable paper name
subject_id	uuid	required	Must be available on your subscription
source_document	file or URL	conditional	The homework/question paper (PDF). Required unless solutions_document is supplied
solutions_document	file or URL	conditional	The marking scheme or worked solutions (PDF). It may be supplied alone when it also contains the questions
assessment_type	string	optional	homework (default) or exam
external_reference	string	optional	Your own identifier for the paper
code	string	optional	Your own code. Must be globally unique; omit it and we generate one
topic_ids	array	optional	Topic ids belonging to the subject

Idempotency

Send an external_reference and a repeat of the same call returns the
assessment you already created, with 200, instead of a second copy. This
makes a timed-out request safe to retry.

Codes

code is unique across every assessment, so namespace yours (for example
acme:2026:PMX:w27). A code already in use returns 409 with
MARK_ERRORS::CODE_TAKEN. Omit code and we return a generated one for you
to store.

Lifecycle

draft → extracting → review → published. A paper can only be marked
against once it is published; hand-ins sent before then have no answer key
and would fall through to ad-hoc marking. Publishing requires a person to
confirm every question — see Review an assessment.

When homework is supplied without a solutions document, Intu creates a
syllabus- and question-bank-grounded draft answer key. Generated solutions
and success criteria are explicitly flagged and must be confirmed by a
person before publication. PDF transcription never silently invents a
missing answer.