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.
Setup
To use the Submissions API, install the @wix/forms
package using npm or Yarn:
1npm install @wix/forms
or
1yarn add @wix/forms
Then import { submissions }
from @wix/forms
:
1import { submissions } from '@wix/forms'
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:function bulkDeleteSubmission(formId: string, options: BulkDeleteSubmissionOptions): Promise<BulkDeleteSubmissionResponse>
Form ID.
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:function bulkMarkSubmissionsAsSeen(ids: Array<string>, formId: string): Promise<void>
IDs of submissions to mark as seen.
ID of the form which the submissions belong to.
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:function bulkRemoveSubmissionFromTrashBin(formId: string, options: BulkRemoveSubmissionFromTrashBinOptions): Promise<BulkRemoveSubmissionFromTrashBinResponse>
Form ID.
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:function confirmSubmission(submissionId: string): Promise<ConfirmSubmissionResponse>
Submission ID to confirm.
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:function countDeletedSubmissions(formIds: Array<string>, namespace: string, options: CountDeletedSubmissionsOptions): Promise<CountDeletedSubmissionsResponse>
Form IDs.
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.
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:function countSubmissions(formIds: Array<string>, namespace: string, options: CountSubmissionsOptions): Promise<CountSubmissionsResponse>
Form IDs which submissions should be counted.
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.
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:function createSubmission(submission: FormSubmission, options: CreateSubmissionOptions): Promise<CreateSubmissionResponse>
Submission to create.
Optional fields.
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:function deleteSubmission(submissionId: string, options: DeleteSubmissionOptions): Promise<void>
ID of the submission to delete.
Optional fields.
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:function getDeletedSubmission(submissionId: string): Promise<GetDeletedSubmissionResponse>
Submission id.
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:function getMediaUploadUrl(formId: string, filename: string, mimeType: string): Promise<GetMediaUploadURLResponse>
Form ID.
Name of file to upload.
Mime type of file to upload.
For example, 'image/png'
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:function getSubmission(submissionId: string): Promise<GetSubmissionResponse>
ID of the submission to retrieve.
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:function listDeletedSubmissions(formId: string, options: ListDeletedSubmissionsOptions): Promise<ListDeletedSubmissionsResponse>
Form ID.
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
.
PROPERTY | SUPPORTED FILTERS & SORTING |
---|---|
_id | ascending() ,descending() |
formId | ascending() ,descending() |
namespace | eq() |
status | ascending() ,descending() |
_createdDate | ascending() ,descending() |
_updatedDate | ascending() ,descending() |
seen | ascending() ,descending() |
Permission Scopes
For app development, you must have one of the following permission scopes:function querySubmissionsByNamespace(options: QuerySubmissionsByNamespaceOptions): SubmissionsQueryBuilder
Query options.
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:function removeSubmissionFromTrashBin(submissionId: string): Promise<void>
ID of the submission to restore.
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:function restoreSubmissionFromTrashBin(submissionId: string): Promise<RestoreSubmissionFromTrashBinResponse>
ID of the submission to restore.
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:function updateSubmission(_id: string, submission: UpdateSubmission): Promise<FormSubmission>
Submission ID.
Submission to update.