RECIPE: Create a Wix Form

Download skillThe skill is a reference md and part of wix-manage skill. You can use the following command to add the full wix-manage skill to your project:
Copy

Every request and field in this recipe is complete and was verified live: send it as written, with no docs search, article or schema lookup. Only the kinds listed as "Other kinds" in ยง Field types need About Form Fields.

Each call's method page and the response fields the next step reads are below. Cite these pages as the calls' docs sources; none needs a search.

StepCallMethod pageRead from the response
0 ยท 2GET https://www.wixapis.com/form-app-service/v4/restrictionsGet Restrictionsrestrictions.formsLimit.limit, restrictions.fieldsLimit.limit, totalFormCount
2POST https://www.wixapis.com/form-schema-service/v4/formsCreate Formform.id, form.name
3 ยท 1GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&formIds=<formId>List Formsforms[0].formFields, forms[0].steps
3 ยท 2GET https://www.wixapis.com/form-schema-service/v4/forms/<formId>/summaryGet Form SummaryformSummary.fields
3 ยท 3POST https://www.wixapis.com/form-submission-service/v4/submissionsCreate Submissionsubmission.id
3 ยท 3DELETE https://www.wixapis.com/form-submission-service/v4/submissions/<submissionId>Delete Submission200 with an empty body

Standard call shape (every curl below). The <AUTH> placeholder is shorthand for Authorization: Bearer <TOKEN> only. Body-bearing requests also need Content-Type: application/json. Send wix-site-id: <SITE_ID> when the token is account-scoped.

Create a form on a Wix site that appears in the Forms & Submissions dashboard and can be placed in the Editor. Wix Forms backs any form a visitor fills in โ€” a contact or enquiry form, a signup or waitlist, an application, a survey, a quote request, a registration questionnaire, etc. Whether a submission also becomes a CRM contact is the optional per-field contactMapping (ยง Contact fields).

Two exceptions โ€” route there instead:

The askOwner
RSVP to an eventWix Events, which ships its own registration form โ€” Create Event
A bookable service's formWix Bookings

Flow: STEP 0 confirm the app, read the caps โ†’ STEP 1 compose the fields โ†’ STEP 2 one POST, all fields โ†’ STEP 3 verify the read-back (mandatory โ€” the 200 proves nothing).


Silent breakers

Four things are accepted with a 200 and produce a form that is empty, wrong, or invisible. There is no error to react to, so get them right on the first call โ€” each is settled in the step named after it.

  1. App โ€” Wix Forms (New) 225dd912-7dea-4738-8688-4b8c6955ffc2 (STEP 0 ยท 1). 14ce1214-b278-a7e4-1373-00cebd1bef7c is the Old app: never install it or treat it as enough. Get it wrong: UNSUPPORTED_FORM_NAMESPACE, and automations report "Forms app is not installed".

  2. Namespace โ€” wix.form_app.form (STEP 2). Get it wrong: a form under any other namespace (notably the non-existent wix.form_platform.form) reads back fine over the API and is completely invisible in the Forms dashboard and the Editor.

  3. identifier โ€” one of the predefined values in ยง Field types (STEP 1). Get it wrong: the field works over the API but the Wix Forms editor cannot render it, so the owner can't see or edit it. A form whose fields all carry invented identifiers opens empty in the editor.

  4. Layout โ€” every field, SUBMIT_BUTTON included, placed in steps[].layout, with lowercase GUIDs on both sides. Get it wrong: the form appears in the Editor's form picker but renders empty โ€” fields still store values, but nothing shows.

Never create throwaway "test" forms to probe the shape: the form allowance is finite (ยง Plan caps). Assemble the whole form, POST once, then verify (STEP 3).


STEP 0: Preflight โ€” confirm the app, then read the caps

1 ยท Confirm Wix Forms (New) is installed.

Copy

Look for 225dd912-7dea-4738-8688-4b8c6955ffc2 in the response โ€” see List Installed Apps. If it isn't installed, install 225dd912-7dea-4738-8688-4b8c6955ffc2 via the Install Wix Apps recipe. A fresh install returns appInstance.status: "UNKNOWN" until it propagates; if the first create fails with an identity/propagation error, retry once โ€” do not loop.

2 ยท Read the site's caps โ€” Get Restrictions:

Copy

The response holds the plan's limits and the form count. A free site returned restrictions.formsLimit.limit: 4, fieldsLimit.limit: 10, stepsLimit.limit: 3, rulesLimit.limit: 3, features: [] and totalFormCount: 1.

  • fieldsLimit counts INPUT fields per form; display fields and the submit button do not count. A request with more input fields than the limit fails, so put the choice to the user before the create (ยง Plan caps).
  • totalFormCount equal to formsLimit.limit means no free slot (STEP 0 ยท 3).
  • features was empty on a free site. Do not decide plan gating from it: the create's error is the gate for premium fields (ยง Plan caps).

โš ๏ธ Do not read the caps from List Forms Providers Configs. Its restrictions (maxFields: 151 on a free site) are what the app declares for all sites, not this site's limits.

3 ยท Only if you need a free slot: list what exists โ€” GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&fieldsets=METADATA (repeat with &enabled=false) โ€” and DELETE https://www.wixapis.com/form-schema-service/v4/forms/{formId} only for forms that are obviously the install's own default sample (a "Get in touch" form with first_name / email / message). The site may hold the owner's real forms. If it isn't obviously sample data, ask the user first โ€” never delete real content unprompted.


STEP 1: Compose the fields

Build each field from one row of ยง Field types and this template. Block names are the enum in camelCase plus Options: inputType: STRING โ†’ stringOptions, componentType: DATE_TIME โ†’ dateTimeOptions.

Copy

Field types

FieldidentifierinputTypecomponentTypevalidation
Short answer / Long answer (paragraph)TEXT_INPUT / TEXT_AREASTRINGTEXT_INPUT{}
First name / Last name / Company / Job titleCONTACTS_FIRST_NAME / CONTACTS_LAST_NAME / CONTACTS_COMPANY / CONTACTS_POSITIONSTRINGTEXT_INPUT{}
EmailCONTACTS_EMAILSTRINGTEXT_INPUT{ "format": "EMAIL" }
PhoneCONTACTS_PHONESTRINGPHONE_INPUT{ "format": "PHONE" }
Address, one lineCONTACTS_ADDRESSSTRINGTEXT_INPUT{}
LinkURL_INPUTSTRINGTEXT_INPUT{ "format": "URL" }
Number / Rating (1โ€“5)NUMBER_INPUT / RATING_INPUTNUMBERNUMBER_INPUT / RATING_INPUT{}, or minimum / maximum
Date / Birthdate / Date pickerDATE_INPUT / CONTACTS_BIRTHDATE / DATE_PICKERSTRINGDATE_INPUT / DATE_INPUT / DATE_PICKER{ "format": "DATE" }
Time / Date and timeTIME_INPUT / DATE_TIME_INPUTSTRINGTIME_INPUT / DATE_TIME{ "format": "TIME" } / { "format": "DATE_TIME" }
Dropdown / Single choiceDROPDOWN / RADIO_GROUPSTRINGDROPDOWN / RADIO_GROUPenum (ยง Choice fields)
Multi choice / Tag pickerCHECKBOX_GROUP / TAGSARRAYCHECKBOX_GROUP / TAGSitems (ยง Choice fields)
Checkbox: agree / subscribe to emailsCHECKBOX / CONTACTS_SUBSCRIBEBOOLEANCHECKBOX{} (ยง Checkboxes)
Text block / Submit buttonRICH_TEXT / SUBMIT_BUTTONfieldType: DISPLAYโ€”โ€”

Other kinds (tax ID, multi-line address, image choice, file upload, signature, payment, appointment, service pickers) and their blocks are in About Form Fields ยง Field types. File upload, signature and payment fields need a premium plan (ยง Plan caps).

A submission must send a date as 2026-12-05, a time as 14:30:00, a date and time as 2026-12-05T14:30:00, a link with https://, and a number as a JSON number. 14:30, 05/12/2026 and "25" are rejected.

The rules below apply to every field.

  • Send validation on every input field, as {} when the row has no format (choice fields excepted, ยง Choice fields).

โš ๏ธ Take inputType and componentType from the same row; never mix rows. A pair that isn't valid together (STRING with CHECKBOX_GROUP, say) is stored with no view, and the field disappears without an error.

  • required goes at inputOptions.required โ€” beside target and inputType โ€” NOT inside validation, where it is accepted and silently discarded. validation carries value constraints only (format, enum, minimum, minLength, items).
  • id must be a fresh lowercase GUID (uuidgen | tr 'A-Z' 'a-z') โ€” never typed from memory, never reused from the examples. An uppercase id is stored lowercase, so the layout's fieldId no longer matches and the field is silently unplaced.
  • target is the immutable submission key โ€” a unique lowercase snake_case string per field (e.g. first_name_f409).
  • Every example value you author is visitor-visible. A placeholder, label or hint carrying a phone number, postcode, currency or date must follow the site's country, not a US/UK default.

Choice fields โ€” the identifier is what routes the renderer

A choice field declares its choices twice, and both declarations are required. Every option carries its own lowercase GUID id, a value and a label; validation.enum (for STRING) or validation.items.stringOptions.enum + itemType (for ARRAY) lists every one of those values. An empty validation is a free-text field, not a dropdown, and it is accepted with a 200.

โš ๏ธ A choice field whose identifier isn't the choice kind is stored as a plain text input. identifier: "TEXT_INPUT" with componentType: "DROPDOWN" returns 200 and reads back carrying textInputOptions: the identifier routes the renderer. Fix the identifier; re-sending the same field reproduces it.

โš ๏ธ ARRAY fields fail after creation. A malformed arrayOptions.validation.items (missing itemType, empty items) passes STEP 3's checks 1โ€“2, but every submission then 400s. STEP 3 check 3 is the only proof.

A dropdown, in full โ€” copy this and swap the label, target, options and every GUID:

Copy

A single choice is the same field with RADIO_GROUP as identifier and componentType, radioGroupOptions as the block, and "numberOfColumns": "ONE" beside options.

A multi choice ("select all that apply"), in full. It is an ARRAY field: the accepted values go in validation.items, with itemType beside the enum, and it submits an array of option values:

Copy

A date field, in full (DATE_PICKER shows a calendar; swap both values for it):

Copy

A tag picker is the same with TAGS, tagsOptions and "numberOfColumns": "ZERO".

The user asks forField
"Agree to the terms / privacy policy", a waiver, any box the visitor must tick to sendCHECKBOX, with "required": true
"Permission to send newsletters / mailings / offers", "GDPR consent to marketing", "subscribe"CONTACTS_SUBSCRIBE, with the SUBSCRIPTION contact mapping. Keep it optional, so a visitor can send the form without opting in
BothA required CHECKBOX and an optional CONTACTS_SUBSCRIBE

A ticked CONTACTS_SUBSCRIBE sets the email of the submission's contact to subscriptionStatus: SUBSCRIBED; unticked leaves it NOT_SET. Keep a CONTACTS_EMAIL field on the form. A plain CHECKBOX stores true / false and subscribes nobody.

The label is a rich-content object inside checkboxOptions. validation: {} goes in booleanOptions, beside componentType: on a CONTACTS_SUBSCRIBE field, a missing or misplaced validation rejects the create with 400 Upsert contact trigger SUBSCRIPTION field with target <target> doesn't have correct validation set.

Copy

A required agreement checkbox, in full โ€” no pii, no contactMapping:

Copy

To link a policy the user gave you, split the label text and give the linked part a decoration:

Copy

Without a URL from the user, send the text alone.

Contact fields

A CONTACTS_* field writes its value to the contact the submission creates or updates. It sets "pii": true and inputOptions.contactMapping:

identifiercontactMapping
CONTACTS_FIRST_NAME / _LAST_NAME / _COMPANY / _POSITION / _BIRTHDATE / _TAX_ID{ "contactField": "FIRST_NAME" }, LAST_NAME, COMPANY, POSITION, BIRTHDATE, VAT_ID
CONTACTS_EMAIL / _PHONE / _ADDRESS{ "contactField": "EMAIL", "emailInfo": { "tag": "UNTAGGED" } }; PHONE with phoneInfo, ADDRESS with addressInfo, same tag
CONTACTS_SUBSCRIBE{ "contactField": "SUBSCRIPTION", "subscriptionInfo": { "subscriptionChannels": ["EMAIL"] } }

โš ๏ธ Never use postSubmissionTriggers.upsertContact to map contacts Older recipes and samples used it, but it is a noop / response-only. Use per-field contactMapping instead.

Sections and pages

Each steps entry is one page with its own layout; row restarts at 0 in each. For "add a second section" or "put the consent on page 2", add a step and place its fields there. Place SUBMIT_BUTTON once, in the last step; on a multi-page form also set nextPageText and previousPageText in its pageNavigationOptions. stepsLimit (STEP 0 ยท 2) caps the pages.

For a heading or note between fields, add { "id": "<GUID>", "identifier": "RICH_TEXT", "fieldType": "DISPLAY", "displayOptions": { "displayFieldType": "RICH_CONTENT", "richContentOptions": { "richContent": { "nodes": [ <PARAGRAPH node, as in the checkbox label> ] } } } }. Display fields do not count against the field cap, but they need a layout item.


STEP 2: Create the form โ€” one POST, all fields

The request below is a complete contact form. Start from it and add the fields from STEP 1; it needs no other page.

Copy

Keep form.id from the response. Read back form.name too: a colliding name is silently saved as a numbered variation.

spamFilterProtectionLevel defaults to ADVANCED; set it only to change that. submitSettings is optional; if you send submitSuccessAction: "THANK_YOU_MESSAGE", send thankYouMessageOptions with it, as above, or the create returns 400 submitSuccessAction and the corresponding thank_you_message_options field must be passed together.

A 200 proves nothing. Always run STEP 3. Every failure mode in ยง Silent breakers returns 200.


STEP 3: Verify the form persisted (mandatory)

1 ยท List it back and diff against what you sent:

Copy

Confirm the id appears, that formFields[] covers every field you sent, that steps is non-empty and places every field, and that each field's inputOptions.required matches what you sent โ€” a misplaced required is dropped silently and this read-back is the only signal.

Also assert every returned formFields[].identifier is a value from ยง Field types (or, for the other kinds, About Form Fields). An invented identifier is stored and returned like any other, so no other check flags it, and the owner cannot see the field in the editor.

2 ยท Verify the dashboard and Editor will actually render it:

Copy

Assert formSummary.fields has one entry per input field you sent (every field except DISPLAY ones, contact-mapped or not). An empty or short list means the owner sees an empty form: do not report success; fix the layout placement or the GUID casing, then re-verify. This check covers placement only, not identifiers.

3 ยท If the form has an ARRAY field (CHECKBOX_GROUP / TAGS / IMAGE_CHOICE), send one real submission. Checks 1โ€“2 both pass on a malformed arrayOptions.validation.items while every submission 400s:

Copy

Assert 200, not 400 SUBMISSION_VALIDATION. Then delete the test submission, with submission.id from that response, so the owner's dashboard stays clean:

Copy

A test submission proves value types and formats only (ยง Field types). It is accepted with a required field missing, a required checkbox false, or a choice value that is not in the options. So prove required and the options from the read-back in check 1, never from a submission.

4 ยท Hand back the dashboard links (see Forms Dashboard Navigation):

Copy

Changing a form that already exists

Adding, relabelling, re-requiring, reordering or retiring a field on a live form is a PATCH, not a second create โ€” see Update Form. Never delete-and-recreate: the formId is what everything downstream holds.


Plan caps โ€” surface the choice, never engineer around it

These limits return a real 400 on create. Do not work around any of them. Put the choice to the user โ€” reduce, or upgrade โ€” with the MSID and the upgrade link, wait for their answer, then create and verify.

  • Field count โ€” Field count reached its limit of N is the plan cap (fieldsLimit, 10 on a free site), counting INPUT fields only. FORM_FIELDS_COUNT_EXCEEDED is the schema-service ceiling, counting all fields. For either, do NOT split the form across several schemas: reduce the fields, or upgrade.
  • Step count (Steps count reached its limit of N, stepsLimit) and condition count (formRules.length, rulesLimit) โ€” collapse into fewer pages or rules, or upgrade.
  • Form count (NAMESPACE_FORMS_COUNT_EXCEEDED, NAMESPACE_DELETED_FORMS_COUNT_EXCEEDED, or FORM_SIZE_EXCEEDED for a single oversized schema) โ€” the site hit its total-form (or trash-bin) cap. Independently of the plan, formFields has a hard ceiling of 500 items. Upgrade, or free a slot per STEP 0 ยท 3 โ€” deleting only what is clearly install sample data.
  • Premium fields โ€” file upload, signature and all four payment fields need a Core plan or higher; payment fields additionally need Wix eCommerce. Appointment needs Wix Meetings; the service pickers need Wix Services. A create including one of these on a site without the plan or app fails. Do NOT suggest inlining files as base64 โ€” it stores no real file. Drop the field, or upgrade.

โš ๏ธ A plan cap is a hard block on the run. The form does not exist, so nothing that depends on its formId or targets can be built "in the meantime".


Automations on form submission

To auto-respond to submissions, the automation's trigger belongs to the app that owns the form โ€” and the two Forms apps have different trigger keys:

AppappIdTrigger key for "Form submitted"
Wix Forms (New)225dd912-7dea-4738-8688-4b8c6955ffc2wix_form_app-form_submitted

The app and the key must be the same generation. A v4 form belongs to the New app, so its automation uses wix_form_app-form_submitted with the New app installed. FAILED_PRECONDITION: "Forms app is not installed on the site" where Wix Forms visibly is installed means only the Old app is: fix it at STEP 0 ยท 1, not by swapping trigger keys.

To confirm the pair on the site, use Query Triggers filtered by appId.


Troubleshooting

Error / symptomCauseFix
UNSUPPORTED_FORM_NAMESPACE, or Permissions for given namespace not foundWix Forms (New) not installed, or a namespace other than wix.form_app.formInstall 225dd912-7dea-4738-8688-4b8c6955ffc2; use wix.form_app.form
Automation create fails FAILED_PRECONDITION: Forms app is not installed although Wix Forms is installedThe Old Forms app (14ce1214-โ€ฆ) is installed; the New app's trigger wix_form_app-form_submitted needs 225dd912-โ€ฆInstall 225dd912-โ€ฆ โ€” do not try to fix it by swapping in the Old app's key wix_forms-form_submit. See ยง Automations on form submission
Form appears in the Editor's form picker but renders emptyFields not placed in steps[].layout, or an uppercase id whose stored lowercase form no longer matches fieldIdPlace every field (incl. SUBMIT_BUTTON); use lowercase GUIDs on both sides; re-verify with /summary
Choice field renders as a plain text box, and reads back with textInputOptionsidentifier was TEXT_INPUT rather than DROPDOWN / RADIO_GROUP โ€” componentType alone doesn't route the rendererSet identifier to the choice kind and re-send the field. Deleting and re-adding it with the same identifier reproduces the fallback
Dropdown or single choice reads back with options: [] (verified live 2026-11-04)The options were sent under a wrong key, such as choices instead of options. The 200 drops them without an errorSend them as options in the component block, each with a lowercase GUID id. Check options in the read-back
options[N].id is not a valid GUID on a create or PATCHOption ids were readable slugs (tech-opt-1) or omitted โ€” each needs its own lowercase GUID, client-generatedGenerate one GUID per option (uuidgen); the field's own id being a GUID is not enough
Form lists and summarizes fine, but every submission returns 400ARRAY field with malformed arrayOptions.validation.items โ€” missing itemType, or empty/omitted itemsSet both items.itemType and items.stringOptions.enum; prove it with STEP 3 ยท 3
400 namespace has size 0, expected 10 or more / namespace must not be empty on a readThe namespace query parameter was omitted from GET .../v4/forms (or from the query filter) โ€” it is required on every read, and the violation naming a field makes it look like a body problemAdd ?namespace=wix.form_app.form to the read; leave the payload alone
Unrecognized value passed for enumInvented componentType (e.g. LONG_TEXT_INPUT)Use the componentType from ยง Field types โ€” a long answer is identifier: TEXT_AREA with componentType: TEXT_INPUT
Field count reached its limit of N / FORM_FIELDS_COUNT_EXCEEDEDField count reached its limit of N is the plan cap on INPUT fields (fieldsLimit in STEP 0 ยท 2). FORM_FIELDS_COUNT_EXCEEDED is the schema-service ceiling, counting all fieldsยง Plan caps: reduce or upgrade. Never split across schemas
Upsert contact trigger SUBSCRIPTION field with target โ€ฆ doesn't have correct validation setThe CONTACTS_SUBSCRIBE field has no booleanOptions.validation, often because validation was put inside checkboxOptionsSend "validation": {} in booleanOptions, beside componentType (ยง Checkboxes)
submitSuccessAction and the corresponding thank_you_message_options field must be passed togethersubmitSettings.submitSuccessAction sent without its options blockSend thankYouMessageOptions with THANK_YOU_MESSAGE (STEP 2), or leave submitSettings out
DUPLICATED_FIELD_TARGETS / DUPLICATED_FIELD_IDS / MISSING_FIELD_TARGETSReused target or id, or omitted targetGive every field a unique lowercase GUID id and a unique snake_case target
Form saved under a different name than requestedNames are unique per namespace; a collision saves a numbered variationRead name from the response and report the actual name

Last updated: 5 November 2026

Did this help?