22 "decision": "There is no form create. Add one control per call with a single-key oneof body — { text | phone | address | date | additionalGuests | dropdown | checkbox | radioButton: { … } } — against the event's existing form. Response returns the generated control id plus the whole modified form. Read back with GET /events/v3/events/{eventId}?fields=FORM. Verified live on a DRAFT event."
23 },
24 "reliability": {
25 "status": "reliable",
26 "flags": []
27 },
28 "pitfalls": [
29 {
30 "code": "per-event-config-not-records",
31 "severity": "warning",
32 "summary": "The form is per-event configuration (an ordered list of controls), not standalone records: there is no create — controls are added/updated on the event's existing form. Historical submissions do not live here; they arrive as RSVP/order data."
33 },
34 {
35 "code": "pinned-required-controls",
36 "severity": "warning",
37 "summary": "VERIFIED LIVE 2026-08-16: a freshly created event already has system controls `name` (type NAME, orderIndex 0) and `email` (type INPUT, orderIndex 1), both system:true and mandatory; added controls append from orderIndex 2. Source forms that made name/email optional or reordered them cannot be reproduced — faithfulness-ledger entry."
38 },
39 {
40 "code": "control-ids-are-not-guids",
41 "severity": "warning",
42 "summary": "CORRECTED 2026-08-16 (live): the docs call the returned control id a \"generated unique input control GUID\", but the first added custom control came back with id `custom` and the second with `custom-a5976fed804ff46f`. Treat the id as an opaque server string, capture it from the AddControl response, and never construct or assume it — RSVP form.inputValues are addressed by input NAME anyway."
43 },
44 {
45 "code": "add-control-publishes-the-form",
46 "severity": "warning",
47 "summary": "Per the docs, applying a control change triggers form publishing. Configure the form inside the notification-mute window and before the event itself is published, the way the 2026-08-16 probe did (draft event, muted site)."
48 },
49 {
50 "code": "control-body-is-a-single-key-oneof",
51 "severity": "warning",
52 "summary": "The AddControl body is the control payload itself at top level — no wrapper object, exactly one of phone/address/date/additionalGuests/dropdown/checkbox/text/radioButton. dropdown and radioButton need minItems 2 options; checkbox needs at least 1; unsupported source input types fall back to a text control with a ledger entry."
53 }
54 ],
55 "mappingGuidance": [
56 "Configure after the event is created (draft is fine): replay source custom registration fields (e.g. Event Tickets attendee fields) as one Add Control call each, in source order — controls append in call order.",
57 "Do not re-add name/email; they are system controls on every event. Only their labels can change.",
58 "Before importing RSVPs, read the finished form back with GET /events/v3/events/{eventId}?fields=FORM and build rsvp.form.inputValues from controls[].inputs[].name — unrecognized input names, missing mandatory values, or values outside predefined options fail the RSVP with INVALID_FORM_RESPONSE."
73 "note": "POST /events/v1/events/{eventId}/form/control; body is a single-key oneof"
74 },
75 {
76 "type": "live-run",
77 "path": "migrations/reference-run",
78 "note": "finding #17 follow-up; Form surface spotted at the docs-survey sweep"
79 },
80 {
81 "type": "live-run",
82 "path": "migrations/probe-run-20260812/config/wix.env (target site 00000000-0000-0000-0000-000000000000)",
83 "note": "KB verification probe 2026-08-16, safe mode on / site muted: added a text control (\"ZZZ Probe Question\", id `custom`, orderIndex 2) and a dropdown control (\"ZZZ Probe Choice\", id `custom-a5976fed804ff46f`, orderIndex 3) to a draft event's form → 200 each; read back via GET /events/v3/events/{id}?fields=FORM; probe event deleted"
84 }
85 ],
86 "notes": "Authored 2026-08-11 from the docs-survey gap (Form). Classified setup-config: per-event form layout applied via Add/Update Control after event creation, no importable records of its own. Promoted to verified-live 2026-08-16; the probe filled in the previously null endpoint (Events V1 form path on a V3 event) and corrected the docs' GUID claim for control ids."