23 "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."
24 },
25 "reliability": {
26 "status": "reliable",
27 "flags": []
28 },
29 "pitfalls": [
30 {
31 "code": "per-event-config-not-records",
32 "severity": "warning",
33 "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."
34 },
35 {
36 "code": "pinned-required-controls",
37 "severity": "warning",
38 "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."
39 },
40 {
41 "code": "control-ids-are-not-guids",
42 "severity": "warning",
43 "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."
44 },
45 {
46 "code": "add-control-publishes-the-form",
47 "severity": "warning",
48 "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)."
49 },
50 {
51 "code": "control-body-is-a-single-key-oneof",
52 "severity": "warning",
53 "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."
54 }
55 ],
56 "mappingGuidance": [
57 "Dependencies: events/event is required because each Add Control call addresses the created event's form by eventId.",
58 "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.",
59 "Do not re-add name/email; they are system controls on every event. Only their labels can change.",
60 "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."
75 "note": "POST /events/v1/events/{eventId}/form/control; body is a single-key oneof"
76 },
77 {
78 "type": "live-run",
79 "path": "anonymized-live-verification",
80 "note": "The docs survey identified the event registration-form surface."
81 },
82 {
83 "type": "live-run",
84 "path": "anonymized-live-verification",
85 "note": "Verified live: text and dropdown controls can be added to a draft event form and read back with GET /events/v3/events/{id}?fields=FORM. Probe records were deleted after verification."
86 }
87 ],
88 "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."