SEED

A field the visitor can fill that isn’t in the schema is silent data loss — no submission, no inbox, no contact, and the submit still resolves true. So never local component state, and never delete-and-recreate a live form: PATCH it, keeping the formId the UI already imports.

The six steps, each with a section below:

1. Authenticate — get an elevated credential; the public client ID cannot write.
2. Install the Wix Forms app — idempotent, and nothing works until it’s there. (create only.)
3. Author the form body — adapt the every-field payload to what the request asks for.
4. Create the form — POST each body; a 200 here means almost nothing. (revising: 4b.)
5. Verify it works — read the form back, and submit to it once for real.
6. Hand off — the verified formId + field targets are written to a file the UI imports.

API reference

Wix Forms is a CRM API, not Business Solutions. Read the page before writing a call you don’t find here — never guess a shape. For anything these pages don’t settle — a response shape you didn’t expect, or an operation this doc doesn’t cover — use the documentation skill available in your environment to search + read the live Wix API reference.

⛔ Additive only — never delete, reset, or overwrite existing forms, even ones that look like the install’s own sample.

⚠️ Seed BEFORE the form’s UI. Forms is the one vertical that does not run in parallel with the client: its inputs bind to the schema’s field targets, so nothing may be built against a form that hasn’t been created and verified.

1 · Authenticate

Every call in this doc needs an elevated credential — a connector/OAuth access token, or a Wix API key. The public WIX_CLIENT_ID cannot write; see the platform doc’s seed-auth step. There is no helper module — you make each call yourself with the shapes below.

Never inline the raw token/API key into a command — it would end up in the transcript, exec logs, and shell history. Keep it in a variable and reference it. On Base44 (and any exec-tool platform), take it from the connector and call with fetch() rather than shelling out to curl:

On any other platform, load it into an env var from your secret manager and don’t echo it. Either way, every call below sends the same three standard headers — referred to as such from here on:

2 · Install the Wix Forms app

225dd912-7dea-4738-8688-4b8c6955ffc2 is the Wix Forms app. Until it is installed every Form Schemas call fails with UNSUPPORTED_FORM_NAMESPACE, so run this before step 4. The call is idempotent — re-installing returns 200 — and Base44 sites often don’t have the app, so re-running costs nothing.

3 · Author the form body — every field type

There is one create call: POST https://www.wixapis.com/form-schema-service/v4/forms with { "form": { "namespace": "wix.form_app.form", … } } — that namespace is the Wix Forms app’s, and the only one the owner’s dashboard shows. You author that body, starting from the payload below and adapting it to the request.

The payload is one form holding every field type Wix Forms supports. Each field block is copied verbatim from the official Create Form examples, so the identifier / inputType / componentType triple, the options objects and the validation shapes are the ones Wix actually accepts. (Two exceptions: Donation comes from About Form Fields, and Custom price is the one field with no shipped example — it is composed from the property reference.)

(Authoring side: which JSON creates each field. The rendering side — which control each one wants and what its value looks like — is the matching table in INSTRUCTIONS.md; they join on identifier.)

* A display field sets fieldType: "DISPLAY" and has neither an input type nor a component type — the value shown is its displayOptions.displayFieldType.

Non-negotiable rules for adapting the payload

Change the fields, labels, options and targets freely — these seven rules must still hold in whatever you send. Break one and the create still returns 200; the damage shows up in the owner’s dashboard, or on the first real submission.

• Every id is a lowercase UUID v4, unique within the form — generate it for each field and every choice option. Then use those UUIDs where reference to a field or an option is required.
• Use only form.formFields for fields, never form.fields - that’s legacy API
• steps must reference every field, including the SUBMIT_BUTTON. Field that is not referenced in any step will not be visible in the business manager.
• required lives at inputOptions.required, never inside a validation block.
• validation is always present, even as {}, and nests under the inputType options object — not the componentType one.
• A choice field’s identifier IS its kind — DROPDOWN, RADIO_GROUP, CHECKBOX_GROUP, TAGS — matching the componentType, never TEXT_INPUT: the identifier routes the field to its renderer, so TEXT_INPUT + componentType: DROPDOWN is accepted and stored as a text input. (A long answer is TEXT_AREA for the same reason.)
• A choice field declares its options twice — the component’s options[] and the validation enum (STRING) or items.stringOptions.enum + itemType (ARRAY) — and the two must agree. Get it wrong and the create still returns 200: the field is created as a plain text box, losing its choices. Only the 5a component check catches it.
• A choice field that came back as a text box: read which options block came home. textInputOptions where you sent dropdownOptions is that fallback — and with a well-formed block and enum, the cause is the identifier. Re-sending it, or delete-and-re-add with the same identifier, reproduces it.
• target is the immutable submission key: starts with an ASCII letter, letters/digits/_ only, no __, unique within the form. Use field’s label converted to snake_case with _ and 6 random alphanumeric
  characters as the field target, e.g. “First name” -> first_name_a689be.

4 · Create the form

One POST per form body, to the Form Schemas v4 endpoint — a CRM API, not Business Solutions, always on the public host, never /_api/:

Read form.id from the response — that’s the formId the rest of the run carries. Record it the moment it comes back, before anything else: it is the only way a later attempt can tell a form this run created from one the owner already had. Forms are independent (no shared revision), so create them in any order.

Three things to check before you POST. The API accepts the first two and loses the field; the third leaves you with a second form:

• the body has at least one INPUT field — a form of nothing but a submit button collects nothing;
• no two fields share a target. The server keeps one; every other field with that key silently stores nothing.
• no form of this name exists yet — GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form, comparing name exactly. Wix does not reject a duplicate name; it silently appends a counter ("Contact" → "Contact 1"), so create is not idempotent and nothing tells you a retry duplicated a form. A name matching a form this run created (per the id you recorded above) → reuse that formId rather than creating again. A name you have no record of creating is the owner’s: additive only, so leave it alone and pick a different name or ask.

An orphan you created in this run is yours to clear — DELETE .../v4/forms/<formId> is a soft delete to the trash bin, so it is recoverable. Anything you did not create stays untouched.

A 200 here proves almost nothing. Most mistakes in a form body are accepted at create and surface only in the owner’s dashboard or on the first real submission — step 5 is what actually proves the form works. Two failures worth recognizing before you retry:

• A transient 5xx, an identity/propagation error right after install, or a timeout leaves you not knowing whether the create landed. Re-list by name before retrying — never blind-retry the POST, because the duplicate it may create is silent. One retry once the list comes back empty; never a loop.

• Plan gates are a hard block, not a note-and-continue. FIELDS_COUNT_RESTRICTIONS_ERROR (per-form field cap), FILE_UPLOAD_RESTRICTIONS_ERROR (upload/signature/payment below Core) and FORMS_COUNT_RESTRICTIONS_ERROR (site form cap) each mean reduce or upgrade — put the choice to the user with their dashboard link and wait for an answer. Never split a form across schemas to dodge the field cap, never inline a file as base64, and never create throwaway forms to probe the shape.

  The field cap cannot be read in advance. listFormsProvidersConfigs reports the Forms app’s ceiling, not the site’s plan cap — on a free site it returns maxFields: 150 while the create is rejected with "Field count reached its limit of 10". The cap is per plan, not per app. Treat the create as the only authority on the number: budget conservatively while authoring step 3 rather than discovering the limit after a full authoring pass, and count every entry in formFields, the SUBMIT_BUTTON included.

4b · Revising a form later

Add a field, relabel one, tighten a rule, retire one — a PATCH, never a second create. Everything above still applies; this is the delta.

Read the form back first — you need its revision. The formId comes from src/rest/wix-forms.config.js (WIX_FORMS.<key>.formId), never typed by hand:

• namespace is a required query parameter on the read, hence the ?namespace= above. Without it the read 400s with namespace has size 0, expected 10 or more — a violation naming a field, so it reads like a body problem. Fix the call, not the payload.
• The read-back is the PATCH body. Apply the change to what the GET returned and send that. namespace is immutable and travels along; there is no fieldMask, and no revision outside form. Inventing either is a silent partial write.
• formFields replaces wholesale. Wix: “Any field that’s missing from the array you send is moved to deletedFormFields, so resend every field you want to keep.” steps behaves the same way. Drops are recoverable from deletedFormFields — if you notice, which is step 5’s job.
• A stale revision is rejected — re-GET and re-apply; never guess or increment it.
• A new field needs three things generated: a fresh UUID id, a target unique in the form (job_industry_7f2b), and — for a choice field — an options block whose enum and options[] agree. Step 3 is the shape, and its warnings still hold.

Add the layout item too — append to steps[<n>].layout.large.items, mirroring into medium / small if the form has them:

A field missing from the layout isn’t dropped, but it sorts last and has no defined position in the owner’s builder. To place it mid-form, insert at that row and bump every item at or after it — row restarts at 0 per step.

Changing a field’s component type in place — a text input that should have been a dropdown — means the choice identifier and only the new options block; don’t leave textInputOptions beside dropdownOptions. A read-back still showing textInputOptions is the identifier, not the block.

The other revisions:

• label, placeholder, options, validation, order — patch and stop. The client reads all of those live from the schema, so no config rewrite and no code change follows.
• retiring a field the form has submissions for — set hidden: true (“hidden from submitters”: the field stops being rendered, and the submissions already collected under it keep their meaning) rather than dropping it from the array. Drop only a field added by mistake in this same run.
• never rename a target — it’s the storage key, so a rename orphans every submission already collected under the old one. Change the label instead.

Then re-run step 5 in full — a PATCH regresses a form exactly as a create does, and §5a is where a dropdown that silently became a text input gets caught. Then step 6, revising: add the read-back target to src/rest/wix-forms.config.js (the one sanctioned edit to that file outside a seed run, and only after step 5 passes) and wire the control per INSTRUCTIONS.md. The field is live for new submissions; past ones don’t carry it. Step 4’s plan gates apply to an added field too.

5 · Verify it works

All four calls are yours to make, and the last one needs a submission you compose from this form’s schema. All four use the standard headers from step 1.

A 200 on create means the body parsed — nothing more. Every mistake below returns 200 and surfaces only in the owner’s dashboard or on the first real submission.

5a · Read the form back

formIds narrows the listing to exactly what you created, so you assert against it directly. Then, against the returned form.formFields:

• Every target you sent is there. One that isn’t means the field didn’t persist — usually an identifier Wix doesn’t recognize, which is dropped without an error.
• Every inputOptions.required reads back as you sent it. A required key placed inside a validation block is accepted and then discarded, so the form ships with nothing mandatory. This diff is the only signal you will ever get.
• Every choice field is still a choice field. For each DROPDOWN / RADIO_GROUP / CHECKBOX_GROUP / TAGS you sent, assert the read-back still carries that componentType, that its options[] is non-empty, and that it agrees with the validation enum. A malformed options block is accepted at create and comes back as a plain text input — target intact, required intact — so every other check in step 5 passes and the field silently loses its choices.
• Keep the read-back targets. These, not the ones you authored, are what goes into step 6.

5b · Check the dashboard view

(The summary and the single-form GET take the id in the path, so neither needs the namespace query parameter — every listing read does.)

Assert formSummary.fields is non-empty, with one entry per input field you sent (everything in formFields except the SUBMIT_BUTTON). The summary is exactly what the Wix dashboard renders, so a short or empty count means the form is blank — or partly blank — for the owner, even while the public site submits fine. Non-contact fields count too; don’t expect only the contact-mapped ones.

5c · Submit to it once, for real

This is the check the other two can’t stand in for. An ARRAY field whose validation.items is missing itemType passes 5a and 5b and then 400s form-wide — every field, every visitor. Submitting once is the only proof the form can receive data at all.

What it does not catch: a STRING choice field does not enforce its validation.enum on submit. A dropdown whose enum and options both read back correctly still accepts "Not an option" with a 200. So the probe proves the form receives data; it will not tell you a choice field’s two declarations have drifted apart. Get those right in step 3 — nothing downstream will catch it for you.

Rules for composing submissions — get one wrong and the whole submission fails, not just that value:

• Keys are field targets from the 5a read-back. Never a label, never a field id. A key that isn’t a target in the schema fails the entire submission.

• Include every required field — the server rejects the submission without them — plus every ARRAY field whether required or not, since the ARRAY shape is the thing you’re testing.

• The value’s shape follows the field’s inputType, not its component:

  inputType	value	example
  STRING	a string, formatted per validation.format	"seed-probe@example.com", "2030-01-01", "10:00:00"
  NUMBER	a number	1
  BOOLEAN	a boolean	true
  ARRAY	an array of option values	["Option 1"]
  ADDRESS	an object, only the subfields the form shows	{"country":"US","subdivision":"US-NY","city":"New York","postalCode":"10011","addressLine":"235 West 23rd Street"}
  PAYMENT	an array of {productId, price, quantity}	[{"productId":"<from validation.products>","price":"25","quantity":1}]
  SCHEDULING	{startDate, endDate, timeZone}	{"startDate":"2030-07-02T14:00:00","endDate":"2030-07-02T14:30:00","timeZone":"America/New_York"}

• Use one of the field’s own option values — copy it from the schema rather than retyping the label. The server won’t reject a value outside the enum (see above), so a typo here quietly proves nothing.

• country and subdivision are validated against each other, so send a matching pair or omit subdivision.

• A WIX_FILE field can’t be faked. If a file upload or signature is required, this check can’t run — say so and have the user submit once through the published site instead of recording a pass that never happened.

Assert 200. A 400 SUBMISSION_VALIDATION is a schema bug, not a submission bug — fix the form body and re-create it; never bend the value to get through. The error names the field and the reason under details.validationError.fieldViolations[].data.errors[], each with an errorPath (the target) and an errorType — UNKNOWN_VALUE_ERROR means the key isn’t a target in this form.

5d · Delete the test submission

The id comes from the 5c response as submission.id: REST returns id, not the _id the reference schema shows (that’s the SDK’s shape). Do this every time — the owner’s inbox is a real business inbox, and a probe left in it looks like a real enquiry. If a probe ever escapes, find it with POST /form-submission-service/v4/submissions/namespace/query, filtered by formId and "namespace": "wix.form_app.form".

6 · Hand off

Only once step 5 has passed for every form, write src/rest/wix-forms.config.js — one entry per form, keyed by the form’s name lowercased with each run of non-alphanumerics collapsed to a single _ ("Quote request" → quote_request):

That file is the handoff, and the gate. The UI imports WIX_FORMS from it; no file means the seed did not succeed, so nothing may be built against the form yet. So never write it before step 5 passes, and never invent a formId. If the app’s src/ layout puts its REST layer elsewhere, write it there instead — the path matters less than the file existing before the UI step.

targets is the read-back map of immutable submission keys — the one from 5a, not the one you authored in step 3. Everything else — labels, order, options, validation — the client reads live from the schema, so an owner’s dashboard edit shows on the site with no code change.