Skip to main content
POST
Author Forms and Quizzes
Authoring follows the same draft-then-publish model as the employer builder: the draft is mutable, every publish snapshots an immutable numbered version, and assignments only ever pin published versions. All actions here require project_todos:write.

form_create

string
required
The job whose organization owns the form.
string
required
string
FORM or QUIZ — seeds sensible defaults (new forms default to 1 attempt, new quizzes to 2, with a pass rule).
object
Optional complete question definition; omit to start from the kind’s default draft.
object
Optional attempt policy, pass rule, and result-release settings.
Creation is receipt-idempotent: retrying the same idempotencyKey with the same payload returns the same form; the same key with a different payload returns 409.

form_update_draft

Replaces the draft definition and settings under an optimistic lock.
string
required
number
required
The draft revision you last read. A concurrent edit fails with 409 instead of overwriting.
string
required
object
required
object
required
Question types: SHORT_TEXT, PARAGRAPH, MULTIPLE_CHOICE, CHECKBOXES, DROPDOWN, LINEAR_SCALE, NUMBER, and DATE, plus SECTION and TITLE layout blocks. A question is auto-graded (answer key plus points), manually graded (points awarded by the employer), or informational — never both auto and manual. Settings: attemptPolicy (UNLIMITED or LIMITED with maxAttempts), an optional passRule (percentage or absolute points), and resultRelease (IMMEDIATE or MANUAL).

form_publish

string
required
number
required
Publishes the draft as the next numbered immutable version. Publication validates the definition — for example, a pass rule requires at least one answerable scored question.

form_duplicate and form_archive

form_duplicate copies a form into a fresh draft. form_archive retires the form from new attempts while published versions and response history stay readable.