Read Forms And Submissions

These calls need the Wix Forms app on the site (appDefId 225dd912-7dea-4738-8688-4b8c6955ffc2); a 428, a 400 naming the app, or an empty result on a site that should have content means it is not there. List Installed Apps shows what the site has; Install Wix Apps adds it by that id.

List a site’s forms, find one, and read the submissions sent to it. The usual order is find the form first, then query its submissions by formId. Every call here is a read — nothing on the site changes, so no confirmation is needed.

STEP 1 · Know the namespace — never guess it

Every form and every submission belongs to one namespace: the app that owns the form. Every read except Get Form and Get Submission needs it.

The source is Namespaces of apps made by Wix (opens in a new tab).

• “My forms”, “my contact form”, “form submissions” with no app named → wix.form_app.form.
• You already hold a form → use its namespace field.
• Permissions for given namespace not found: <namespace> → that app is not installed on the site. Stop. Check the site’s apps with List Installed Apps and tell the user the app is missing. Do not try other namespaces (wix.old_form_app.form, wix.forms, …): none of them exist, and each one only costs another failed call.
• List Forms returns "forms": [] for a namespace → it means no forms there, or the wrong namespace. It does not error on a namespace the site lacks.

STEP 2 · Pick the call

⚠️ These look-alike URLs do not exist and return a bare 404:

• /forms/v4/forms, /forms/v4/forms/query, /forms/v4/forms/{formId} — forms live under /form-schema-service/v4/.
• /form-schema-service/v4/submissions/... and /form-submission-service/v4/forms — submissions live under /form-submission-service/v4/submissions/, forms don’t.

Use .../submissions/namespace/query for every submissions query. It is the only submissions query the docs list. Don’t drop namespace from the path.

https://www.wixapis.com/forms/v4/submissions/... (the publicUrl the API spec gives for the submission methods) is the same API under another path, and works too. The /forms/v4/ alias exists for submissions only: /forms/v4/forms still 404s.

STEP 3 · List or find the forms

List every form

• ⚠️ enabled defaults to true, and no value returns both. One call hides every disabled form. With List Forms, make both calls and report both lists, marking the disabled ones. Or use Query Forms with only the namespace filter (below): it returns enabled and disabled forms in one call.
• fieldsets=METADATA returns only the top-level properties (id, name, enabled, dates, namespace) and leaves out fields, steps and rules. Use it whenever you only need names and IDs. Omit it when you need the fields (to read submission answers, see STEP 5).
• Response: forms[] and pagingMetadata. When pagingMetadata.hasNext is true, call again with paging.cursor=<pagingMetadata.cursors.next>.
• To read specific forms, add formIds=<id> (repeat the parameter for each ID).

Find a form by name or date

• Filter and sort fields: id, namespace ($eq only), name ($eq, $ne, $in, $nin, $startsWith), enabled ($eq, $ne), createdDate and updatedDate ($eq, $ne, $gt, $gte, $lt, $lte, $in, $nin). Date operators are $gte / $lte. $ge / $le are rejected. A range needs one condition per operator under $and, exactly as for submissions in STEP 4.
• Query Forms returns enabled and disabled forms together, unless you filter on enabled.
• Response: forms[] and metadata (not pagingMetadata). For the next page, see Paging.

Read one form

Returns form, with formFields (each input field’s inputOptions.target is the key its answers are stored under) and namespace.

STEP 4 · Query the submissions

The latest submissions to one form

• ⚠️ namespace goes inside query.filter. A top-level "namespace" beside query doesn’t count: the call fails with namespace filter is required.
• Leave out formId to read submissions across every form in the namespace.
• Response: submissions[] and metadata (count, hasNext, cursors.next). Each submission has id, formId, status, seen, contactId (when linked to a contact), submitter, createdDate, and submissions (the answers, see STEP 5).

Read one submission

When you already hold a submission ID, read it directly. No namespace is needed:

Returns submission, with the same fields as a query result, including formId (the form it belongs to) and the answers in submissions.

When it was submitted = createdDate

The submission time is createdDate. Filter and sort on it. These fields do not exist, and each one fails with Filter contains unsupported condition or Sort contains unsupported condition: submittedDate, submittedAt, submissionTime, submissionDate, dateCreated, _createdDate.

A date range — one condition per operator, joined with $and

A field takes one operator. Two operators in one object, such as "createdDate": {"$gte": …, "$lt": …}, fail with Field '$lt' is not supported for filter with operator '$eq'. Put each bound in its own condition under $and:

• Write dates as ISO 8601 UTC. For “last week”, work out the week’s start and end from today’s date, and say which dates you used.
• “How many…” in a date range: follow every page and add up metadata.count. There is no total in the response, and Count Submissions takes no date filter.
• “How many…” in total, per form: Count Submissions.

Returns formsSubmissionsCount[], with formId, totalCount and unseenCount for each form.

The fields you can filter and sort by — a closed list

Any other field is rejected. The common wrong ones:

To find a person’s submissions by their email, look up the contact first, then filter submissions by "contactId": "<contacts[0].id>":

No contact found means no submissions linked to that email. See Query Contacts (opens in a new tab).

Paging

Each page holds at most 100 submissions or forms. When metadata.hasNext is true, send the same URL with only the cursor. The cursor carries the filter and sort, including the namespace:

STEP 5 · Read the answers

A submission’s answers are in its submissions object, keyed by each field’s target:

The targets are not labels. To show the user readable answers, read the form once (Get Form) and match each formFields[].inputOptions.target to the label inside that field’s inputOptions, for example stringOptions.textInputOptions.label.

Return only what the user asked for. A submission page can be large. Before you answer or pass results on, keep only the fields you need, such as id, createdDate, contactId and the few answers that matter. Use fieldsets=METADATA on List Forms for the same reason.

To give the user a link to a form’s submissions table, see Forms Dashboard Navigation.

Troubleshooting

Related Documentation

• Update Form and Create Form — changing or building a form
• Forms Dashboard Navigation — links to a form and its submissions table
• List Forms (opens in a new tab) · Query Forms (opens in a new tab) · Get Form (opens in a new tab)
• Query Submissions By Namespace (opens in a new tab) · Count Submissions (opens in a new tab)
• About Submission Values (opens in a new tab) — what each field type stores
• About the Wix API Query Language (opens in a new tab) — $and, $or, paging