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

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

bulkMarkSubmissionsAsSeen( )

Developer Preview

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

Marks form submissions as seen by site collaborators with manage submission permissions.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Submissions
Learn more about permission scopes.
Copy
function bulkMarkSubmissionsAsSeen(ids: Array<string>, formId: string): Promise<void>
Method Parameters
idsArray<string>Required
Submission IDs to mark as seen.

formIdstringRequired
ID of the form which the submissions belongs to.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No

confirmSubmission( )

Developer Preview

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

Confirms a submission.

You can only confirm a submission that has a PENDING status. The default status when a submission is created is CONFIRMED. You can change the default status for individual submissions using the createSubmission() or updateSubmission() methods.

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

countSubmissions( )

Developer Preview

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

Counts the number of submissions belonging to the specified forms.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Submissions
Learn more about permission scopes.
Copy
function countSubmissions(formIds: Array<string>, namespace: string): Promise<CountSubmissionsResponse>
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.
Returns
Return Type:Promise<CountSubmissionsResponse>
Was this helpful?
Yes
No

createSubmission( )

Developer Preview

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

Creates a new submission.

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
Returns
Return Type:Promise<CreateSubmissionResponse>
Was this helpful?
Yes
No

deleteSubmission( )

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 a submission by ID.

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): Promise<void>
Method Parameters
submissionIdstringRequired
ID of the submission to delete.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No

getMediaUploadUrl( )

Developer Preview

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

Retrieves a URL, generated by Media Manager, to use when creating a submission with a field for uploading files.

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( )

Developer Preview

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

Retrieves a submission by ID.

Permission Scopes

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

querySubmissionsByNamespace( )

Developer Preview

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

Creates a query to retrieve a list of submissions.

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
_ideq(),in(),ne(),ascending(),descending()
formIdeq(),in(),ne(),ascending(),descending()
namespaceeq(),in(),ne(),ascending(),descending()
statusascending(),descending()
_createdDateascending(),descending()
_updatedDateascending(),descending()

Permission Scopes

For app development, you must have one of the following permission scopes:
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

updateSubmission( )

Developer Preview

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

Updates a submission.

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