Assign a Quiz

Assigning a quiz is a fan-out, so it carries the full audience safety contract: an explicit audience, strict SELECTED validation, and a signed preflight receipt for broad audiences. The server computes all binding hashes itself — you never hand-craft them. Requires project_todos:write and employer access to the job.

quiz_todo_preflight

A no-write preview of the exact assignment. It mirrors every live gate: the job must have Project To-dos enabled, the version must be published, and ON_PASS requires a pass rule and no manually graded questions — a live-invalid request fails the preflight and returns no receipt.

actionstringbodyrequired

quiz_todo_preflight

jobIdstringbodyrequired

formVersionIdstringbodyrequired

The immutable published version to pin.

completionPolicystringbodyrequired

ON_SUBMIT, ON_PASS, or ON_REVIEW.

audiencestringbodyrequired

No default; SELECTED requires exact same-job active selectedContractIds.

titlestringbody

Optional override; defaults to the form title.

descriptionstringbody

requiredbooleanbody

prioritystringbody

blockingModestringbody

dueOffsetMinutesnumberbody

The preflight response includes the exact job and form version, the live masked recipients and count, future-hire semantics, projected due and blocking behavior, duplicates.sameFormVersion (active to-dos already pinning this exact version), warnings, and — for broad audiences — the receipt to pass back.

quiz_todo_create

Creates the item and every initial assignment atomically. Send the identical payload plus:

idempotencyKeystringbodyrequired

A stable key; retries of the identical request converge and never widen the original fan-out.

preflightReceiptstringbody

Required for ACTIVE, FUTURE, and ACTIVE_AND_FUTURE.

allowDuplicatebooleanbody

Overrides the exact-duplicate refusal.

Normalized result

{
  "ok": true,
  "action": "quiz_todo_create",
  "itemId": "…",
  "versionId": "…",
  "audience": "ACTIVE",
  "includesFutureHires": false,
  "fanOut": {
    "matchedContracts": 2,
    "createdAssignments": 2,
    "skippedExistingAssignments": 0,
    "failedAssignments": 0,
    "assignmentIds": ["…", "…"]
  },
  "recipients": [{ "contractId": "…", "displayName": "Alex B." }],
  "replayed": false,
  "warnings": []
}

failedAssignments is always 0 on success: the transaction cannot commit a partial fan-out. skippedExistingAssignments counts recipients who already held this operation’s assignment on a convergent retry. Assigned quizzes are immediately visible to the AI trainers they target.