Introduction

The Form Submissions API allows you to create and manage submissions for a form on your site. When a site visitor fills out a form, a submission is created. You can then use the Submissions API to view and manage the submissions made to your form.

With the Form Submissions API, you can:

  • Query and manage a submission.
  • Retrieve the total number of submissions per form.
  • Confirm a submission or mark submissions as seen.
  • Retrieve a media upload URL to use when creating or updating submissions for forms that include a field for uploading files.

Before you begin

It’s important to note the following points before starting to code:

  • You must first have a form on your site in order to manage submissions.

Terminology

  • Submission: Data received when a form is submitted by a site visitor.
  • Submissions Table: A table or database that records submissions to a form.
  • Media Upload URL: A URL used to upload a file to a form.
Was this helpful?
Yes
No

Setup

To use the Submissions API, install the @wix/forms package using npm or Yarn:

Copy
1
npm install @wix/forms

or

Copy
1
yarn add @wix/forms

Then import { submissions } from @wix/forms:

Copy
1
import { submissions } from '@wix/forms'
Was this helpful?
Yes
No
bulkDeleteSubmission( )
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes submissions by IDS for specific form.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.
Copy
function bulkDeleteSubmission(formId: string, options: BulkDeleteSubmissionOptions): Promise<BulkDeleteSubmissionResponse>
Method Parameters
formIdstringRequired
Form ID.
optionsBulkDeleteSubmissionOptions
Returns
Return Type:Promise<BulkDeleteSubmissionResponse>
Was this helpful?
Yes
No
bulkMarkSubmissionsAsSeen( )

Marks form submissions as "seen".

Note: The Submissions API is only available in Wix Studio and Editor X.

This function marks the submissions as if they were seen by the site owner. Only site collaborators with the Manage Submission permissions can mark submissions.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Manage Orders
Read Orders
Read Submissions
Learn more about permission scopes.
Copy
function bulkMarkSubmissionsAsSeen(ids: Array<string>, formId: string): Promise<void>
Method Parameters
idsArray<string>Required
IDs of submissions to mark as seen.
formIdstringRequired
ID of the form which the submissions belong to.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No
bulkRemoveSubmissionFromTrashBin( )
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Remove multiple deleted submissions

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.
Copy
function bulkRemoveSubmissionFromTrashBin(formId: string, options: BulkRemoveSubmissionFromTrashBinOptions): Promise<BulkRemoveSubmissionFromTrashBinResponse>
Method Parameters
formIdstringRequired
Form ID.
optionsBulkRemoveSubmissionFromTrashBinOptions
Returns
Return Type:Promise<BulkRemoveSubmissionFromTrashBinResponse>
Was this helpful?
Yes
No
confirmSubmission( )

Confirms a submission.

Note: The Submissions API is only available in Wix Studio and Editor X.

You can only confirm a submission that has a PENDING status. When using forms from the Wix Pricing Plans app, the default submission status is PENDING. When using forms from the Wix Forms app, the default form submission status is CONFIRMED. You can change the default status for individual submissions using the updateSubmission() method.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.
Copy
function confirmSubmission(submissionId: string): Promise<ConfirmSubmissionResponse>
Method Parameters
submissionIdstringRequired
Submission ID to confirm.
Returns
Return Type:Promise<ConfirmSubmissionResponse>
Was this helpful?
Yes
No
countDeletedSubmissions( )
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Note: The Submissions API is only available in the Wix Studio editor.

Counts the number of submissions belonging to the specified forms.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Manage Orders
Read Orders
Read Submissions
Learn more about permission scopes.
Copy
function countDeletedSubmissions(formIds: Array<string>, namespace: string, options: CountDeletedSubmissionsOptions): Promise<CountDeletedSubmissionsResponse>
Method Parameters
formIdsArray<string>Required
Form IDs.
namespacestringRequired
Identifies the app which the form submissions belong to. For example, the namespace for the Wix Forms App is "wix.form_app.form". The namespace of a submission can be retrieved using the Get Submission endpoint.
optionsCountDeletedSubmissionsOptions
Returns
Return Type:Promise<CountDeletedSubmissionsResponse>
Was this helpful?
Yes
No
countSubmissions( )

Counts the number of submissions belonging to the specified forms.

Note: The Submissions API is only available in Wix Studio and Editor X.

The countSubmissions() function is useful for analytics and tracking purposes. For example, if you have a contact form on your website, you can use this function to track how many submissions it receives daily, weekly, or monthly.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Manage Orders
Read Orders
Read Submissions
Learn more about permission scopes.
Copy
function countSubmissions(formIds: Array<string>, namespace: string, options: CountSubmissionsOptions): Promise<CountSubmissionsResponse>
Method Parameters
formIdsArray<string>Required
Form IDs which submissions should be counted.
namespacestringRequired
The app which the form submissions belong to. For example, the namespace for the Wix Forms app is wix.form_app.form. Call getSubmission() to retrieve the namespace.
optionsCountSubmissionsOptions
Returns
Return Type:Promise<CountSubmissionsResponse>
Was this helpful?
Yes
No
createSubmission( )

Creates a submission.

Note: The Submissions API is only available in Wix Studio and Editor X.

The createSubmission() function is an alternative way to the WixFormsV2 element for submitting a form. In this case, clicking the submit button is unnecessary, the submission is automatically created when calling this function.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.
Copy
function createSubmission(submission: FormSubmission, options: CreateSubmissionOptions): Promise<CreateSubmissionResponse>
Method Parameters
submissionFormSubmissionRequired
Submission to create.
optionsCreateSubmissionOptions
Optional fields.
Returns
Return Type:Promise<CreateSubmissionResponse>
Was this helpful?
Yes
No
deleteSubmission( )

Deletes a submission.

Note: The Submissions API is only available in Wix Studio and Editor X.

This function moves the form submission into the trash bin. To delete the submission permanently, change the default permanent field value to true.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.
Copy
function deleteSubmission(submissionId: string, options: DeleteSubmissionOptions): Promise<void>
Method Parameters
submissionIdstringRequired
ID of the submission to delete.
optionsDeleteSubmissionOptions
Optional fields.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No
getDeletedSubmission( )
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Get deleted submission

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Manage Orders
Read Orders
Read Submissions
Learn more about permission scopes.
Copy
function getDeletedSubmission(submissionId: string): Promise<GetDeletedSubmissionResponse>
Method Parameters
submissionIdstringRequired
Submission id.
Returns
Return Type:Promise<GetDeletedSubmissionResponse>
Was this helpful?
Yes
No
getMediaUploadUrl( )

Retrieves a URL generated by the Media Manager to use when creating a submission that includes a field for uploading files.

Notes:

  • The Submissions API is only available in Wix Studio and Editor X.
  • You need at least a Standard Premium plan for your site to upload files.

To learn how external clients can use the generated upload URL to upload a file to the Media Manager, see Upload API.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.
Copy
function getMediaUploadUrl(formId: string, filename: string, mimeType: string): Promise<GetMediaUploadURLResponse>
Method Parameters
formIdstringRequired
Form ID.
filenamestringRequired
Name of file to upload.
mimeTypestringRequired
Mime type of file to upload. For example, 'image/png'
Returns
Return Type:Promise<GetMediaUploadURLResponse>
Was this helpful?
Yes
No
getSubmission( )

Retrieves a submission by ID.

Note: The Submissions API is only available in the Wix Studio editor and Editor X.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Manage Orders
Read Orders
Read Submissions
Learn more about permission scopes.
Copy
function getSubmission(submissionId: string): Promise<GetSubmissionResponse>
Method Parameters
submissionIdstringRequired
ID of the submission to retrieve.
Returns
Return Type:Promise<GetSubmissionResponse>
Was this helpful?
Yes
No
listDeletedSubmissions( )
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

List deleted submissions

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Manage Orders
Read Orders
Read Submissions
Learn more about permission scopes.
Copy
function listDeletedSubmissions(formId: string, options: ListDeletedSubmissionsOptions): Promise<ListDeletedSubmissionsResponse>
Method Parameters
formIdstringRequired
Form ID.
optionsListDeletedSubmissionsOptions
Returns
Return Type:Promise<ListDeletedSubmissionsResponse>
Was this helpful?
Yes
No
querySubmissionsByNamespace( )

Creates a query to retrieve a list of submissions.

Note: The Submissions API is only available in Wix Studio and Editor X.

The querySubmissionsByNamespace() method builds a query to retrieve a list of submissions from the specified namespace and returns a SubmissionsQueryBuilder object.

Note: You can only query submissions from a specified namespace. Use the query filter on the namespace field, otherwise you will receive an error.

The returned object contains the query definition, which is typically used to run the query using the find() method.

You can refine the query by chaining SubmissionsQueryBuilder methods onto the query. SubmissionsQueryBuilder methods enable you to sort, filter, and control the results that querySubmissionsByNamespace() returns.

The following SubmissionsQueryBuilder methods are supported for querySubmissionsByNamespace(). For a full description of the Submissions object, see the object returned for the items property in SubmissionsQueryResult.

PROPERTYSUPPORTED FILTERS & SORTING
_idascending(),descending()
formIdascending(),descending()
namespaceeq()
statusascending(),descending()
_createdDateascending(),descending()
_updatedDateascending(),descending()
seenascending(),descending()

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Manage Orders
Read Orders
Read Submissions
Learn more about permission scopes.
Copy
function querySubmissionsByNamespace(options: QuerySubmissionsByNamespaceOptions): SubmissionsQueryBuilder
Method Parameters
optionsQuerySubmissionsByNamespaceOptions
Query options.
Returns
Return Type:SubmissionsQueryBuilder
Was this helpful?
Yes
No
removeSubmissionFromTrashBin( )
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Remove deleted submission

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.
Copy
function removeSubmissionFromTrashBin(submissionId: string): Promise<void>
Method Parameters
submissionIdstringRequired
ID of the submission to restore.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No
restoreSubmissionFromTrashBin( )
Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Restores deleted submission

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.
Copy
function restoreSubmissionFromTrashBin(submissionId: string): Promise<RestoreSubmissionFromTrashBinResponse>
Method Parameters
submissionIdstringRequired
ID of the submission to restore.
Returns
Return Type:Promise<RestoreSubmissionFromTrashBinResponse>
Was this helpful?
Yes
No
updateSubmission( )

Updates a submission.

Note: The Submissions API is only available in Wix Studio and Editor X.

Each time the submission is updated, revision increments by 1. The existing revision must be included when updating the submission. This ensures you're working with the latest submission information, and prevents unintended overwrites.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.
Copy
function updateSubmission(_id: string, submission: UpdateSubmission): Promise<FormSubmission>
Method Parameters
_idstringRequired
Submission ID.
submissionUpdateSubmissionRequired
Submission to update.
Returns
Return Type:Promise<FormSubmission>
Was this helpful?
Yes
No