About Form Submissions

With Wix Form Submissions, site owners can manage individual form submissions from site visitors.

The Form Submissions API provides flexibility in managing form submission data and allows your app to:

  • Query and manage submissions for a specified form.
  • Retrieve the total number of submissions per form.
  • Support the ability to upload media files to a media manager folder when forms include "file upload" fields.

Learn more about Wix Forms.

Terminology

  • Submission: Data received when a site visitor submits a form.
  • Media Upload URL: A URL used to upload a file to a form.
  • Namespace: The app that a form belongs to.
Was this helpful?
Yes
No

Form Submissions: Sample Use Cases and Flows

This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation.

Submit a form with media

You can upload media files to a media manager folder by creating a new submission for a form that contains a field for uploading files.

  1. Call Get Media Upload URL to generate the upload URL for the specified file.

  2. Call Create Submission and use the generated URL as the value for the file upload field.

Periodically sync with an external analysis and reporting tool

You can retrieve submission data and upload it to an external data analysis tool. With the external tool, site owners can easily do a statistical analysis of their form submission data.

  1. For the first load, use Query Submissions By Namespace and filter for all submissions whose status has been confirmed.

  2. Extract any desired data from the submissions payload, then upload the data to your app.

  3. For all subsequent loads, use the Query Submissions By Namespace endpoint and filter for submissions that are confirmed and have not yet been seen.

  4. Repeat step 2 to 3 for each subsequent load.

Sync with an external CRM for marketing purposes

Every time a form gets submitted, you can add the form submitter to an external CRM. A site owner can then use their CRM to send marketing emails to their form submitters. This flow relies on forms that requires a submitters email, and on an external CRM service.

  1. When the Submission Created Webhook is triggered, you'll receive the submission in the payload from createdEvent.entity.

  2. Exract the email address from the submissions object.

  3. Check that the email adress is not already listed as a subscriber in the external CRM.

  4. Upload the new subscriber to the CRM.

Was this helpful?
Yes
No

Form Submissions: Supported Filters and Sorting

The following table shows field support for filters and sorting for the form submission object:

FieldSupported FiltersSortable
id$eq, $ne, $in, $ninSortable
createdDate$eq, $gt, $gte, $in, $lt, $lte, $ne, $ninSortable
updatedDate$eq, $gt, $gte, $in, $lt, $lte, $ne, $ninSortable
formId$eq, $ne, $in, $ninSortable
namespace$eq, $ne, $in, $ninSortable
properties$eq, $neSortable
status$eq, $ne, $in, $ninSortable

Related content: API Query Language, Query Submissions

Was this helpful?
Yes
No

Submission Object

Form submission that was created or retrieved.

Attributes
idstringRead-onlyformat GUID
Submission ID.

formIdstringformat GUID
ID of the form which submission belongs to.

namespacestringRead-onlyminLength 10maxLength 50
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.

statusstring
5 supported values:
UNDEFINEDPENDINGCONFIRMEDPAYMENT_WAITINGPAYMENT_CANCELED
Status of the submission.
  • PENDING: When a submission has been created, but has not yet been recorded in the submission table of the forms dashboard.
  • PAYMENT_WAITING: When a submission of form, requiring payment, has been created.
  • PAYMENT_CANCELED: When a submission's of form, requiring payment, order has been canceled.
  • CONFIRMED: When a submission is recorded in the submissions table of the forms dashboard.

submissionsobjectformat map
Submission values where key is the form field and value is the data submitted for the given field.

createdDatestringRead-onlyformat date-time
Date and time the form submission was created.

updatedDatestringRead-onlyformat date-time
Date and time the form submission was updated.

revisionobjectRead-only
Revision number, which increments by 1 each time the form submission is updated. To prevent conflicting changes, the existing revision must be used when updating a form submission.

submitterobject
ID of the creator of the form submission.

seenboolean
Whether the submission was read by a site Extension with permissions to manage submissions.

extendedFieldsobject
Data extensions ExtendedFields.

orderDetailsobject
Order details.
Was this helpful?
Yes
No

PostCreate Submission

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.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/_api/form-submission-service/v4/submissions

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

GetGet Submission

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:
Manage Submissions
Manage Orders
Read Orders
Read Submissions
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
GET
https://www.wixapis.com/_api/form-submission-service/v4/submissions/{submissionId}

Was this helpful?
Yes
No

DeleteDelete Submission

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.Authorization header required - pass the OAuth Access Token
Endpoint
DELETE
https://www.wixapis.com/_api/form-submission-service/v4/submissions/{submissionId}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PatchUpdate Submission

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.Authorization header required - pass the OAuth Access Token
Endpoint
PATCH
https://www.wixapis.com/_api/form-submission-service/v4/submissions/{submission.id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostConfirm Submission

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, PAYMENT_WAITING or PAYMENT_CANCELED status. The default status when a submission is created is CONFIRMED. You can change the default status for individual submissions using the Create Submission or Update Submission endpoints.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/_api/form-submission-service/v4/submissions/{submissionId}/confirm

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostQuery Submissions By Namespace

Developer Preview

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

Returns a list of up to 100 submissions, given the provided paging, filtering, and sorting.

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

For field support for filters and sorting, see Form Submissions: Supported Filters and Sorting.option

To learn about working with Query endpoints, see API Query Language, Sorting and Paging, and Field Projection.

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.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/_api/form-submission-service/v4/submissions/namespace/query

Was this helpful?
Yes
No

PostCount Submissions

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:
Manage Submissions
Manage Orders
Read Orders
Read Submissions
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/_api/form-submission-service/v4/submissions/count

Was this helpful?
Yes
No

PostGet Media Upload URL

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 allow clients to upload a file to a form for submission.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Submissions
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/_api/form-submission-service/v4/submissions/media-upload-url

Was this helpful?
Yes
No

PostBulk Mark Submissions As Seen

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 Extensions with manage submission permissions.

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.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/_api/form-submission-service/v4/bulk/submissions/mark-as-seen

Was this helpful?
Yes
No

Submission Created

Developer Preview

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

Triggered when a submission is restored.

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.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.forms.v4.submission.

slugstring
Event name. Expected created.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

createdEventobject
Event information.
Was this helpful?
Yes
No

Submission Updated

Developer Preview

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

Triggered when a submission is updated, order status associated with submission gets updated or submission is confirmed.

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.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.forms.v4.submission.

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.
Was this helpful?
Yes
No

Submission Status Updated

Developer Preview

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

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.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.forms.v4.submission.

slugstring
Event name. Expected status_updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

actionEventobject
Event information.
Was this helpful?
Yes
No

Submission Deleted

Developer Preview

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

Triggered when a submission is deleted.

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.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.forms.v4.submission.

slugstring
Event name. Expected deleted.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

deletedEventstruct
Event information.
Was this helpful?
Yes
No

Removed Submission From Trash

Developer Preview

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

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.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.forms.v4.submission.

slugstring
Event name. Expected removed_submission_from_trash.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

actionEventobject
Event information.
Was this helpful?
Yes
No