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:
Learn more about Wix Forms.
wix_forms
is installed on the site.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.
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.
Call Get Media Upload URL to generate the upload URL for the specified file.
Call Create Submission and use the generated URL as the value for the file upload field.
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.
For the first load, use Query Submissions By Namespace and filter for all submissions whose status has been confirmed.
Extract any desired data from the submissions
payload, then upload the data to your app.
For all subsequent loads, use the Query Submissions By Namespace endpoint and filter for submissions that are confirmed and have not yet been seen.
Repeat step 2 to 3 for each subsequent load.
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.
When the Submission Created Webhook is triggered, you'll receive the submission in the payload from createdEvent.entity
.
Exract the email address from the submissions
object.
Check that the email adress is not already listed as a subscriber in the external CRM.
Upload the new subscriber to the CRM.
The following table shows field support for filters and sorting for the form submission object:
Field | Supported Filters | Sortable |
---|---|---|
id | $eq , $ne , $in , $nin | Sortable |
createdDate | $eq , $gt , $gte , $in , $lt , $lte , $ne , $nin | Sortable |
updatedDate | $eq , $gt , $gte , $in , $lt , $lte , $ne , $nin | Sortable |
formId | $eq , $ne , $in , $nin | Sortable |
namespace | $eq , $ne , $in , $nin | Sortable |
properties | $eq , $ne | Sortable |
status | $eq , $ne , $in , $nin | Sortable |
Related content: API Query Language, Query Submissions by Namespace
Form submission that was created or retrieved.
Submission ID.
ID of the form which the submission belongs to.
The app which the form submissions belong to. For example, the namespace for the Wix Forms app is wix.form_app.form
. Call Get Submission
to retrieve the namespace.
Status of the submission.
Submission values where key
is the form field and value
is the data submitted for the given field.
Date and time the form submission was created.
Date and time the form submission was updated.
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.
ID of the visitor that submitted the form.
Whether a site owner marked a submission as "seen".
Data extension object that holds users' and apps' fields.
Order details.
Note: This object is only applicable when submittng a form in the Wix Payments app.
Contact ID of a site visitor who created the submission.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Note: The Form Submission API only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms
is installed on the site.
Creates a new submission.
Submission to create.
Captcha token.
The created submission.
curl -X POST \
'http://www.wixapis.com/form-submission/v4/submissions' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"submission": {
"formId": "e62e3011-55cf-4de3-a497-e097b52d86b8",
"submissions": {
"first_name": "Adam",
"last_name": "Fisher"
}
}
}'
{
"submission": {
"id": "e62e3011-55cf-4de3-a497-e097b52d86b7",
"formId": "e62e3011-55cf-4de3-a497-e097b52d86b8",
"namespace": "wix.form_app.form",
"status": "PENDING",
"submissions": {
"first_name": "Adam",
"last_name": "Fisher"
},
"submitter": {
"memberId": "4b42fb49-8c77-4128-859c-8247756f68ef"
},
"seen": false,
"revision": 1,
"createdDate": "2019-10-30T17:22:10.299Z",
"updatedDate": "2019-10-30T17:22:10.299Z"
}
}
There is 1 error with this status code:
There is 1 error with this status code:
There are 2 errors with this status code:
There is 1 error with this status code:
See the entire list and learn more about Wix errors.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Note: The Form Submission API only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms
is installed on the site.
Retrieves a submission by ID.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the submission to retrieve.
The retrieved submission.
curl -X GET \
'http://www.wixapis.com/form-submission/v4/submissions/e62e3011-55cf-4de3-a497-e097b52d86b7' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>'
{
"submission": {
"id": "e62e3011-55cf-4de3-a497-e097b52d86b7",
"formId": "e62e3011-55cf-4de3-a497-e097b52d86b8",
"namespace": "wix.form_app.form",
"status": "PENDING",
"submissions": {
"first_name": "Adam",
"last_name": "Fisher"
},
"submitter": {
"memberId": "4b42fb49-8c77-4128-859c-8247756f68ef"
},
"seen": false,
"revision": 1,
"createdDate": "2019-10-30T17:22:10.299Z",
"updatedDate": "2019-10-30T17:22:10.299Z"
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Note: The Form Submission API only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms
is installed on the site.
Deletes a submission by ID.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the submission to delete.
Whether to permanently delete a submission bypassing the trash bin.
Default: false
Whether to preserve files, associated with the submission. If the value is false
, then the files are deleted after 210 days.
curl -X DELETE \
'http://www.wixapis.com/form-submission/v4/submissions/e62e3011-55cf-4de3-a497-e097b52d86b7' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>'
undefined
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Note: The Form Submission API only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms
is installed on the site.
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Submission ID.
Submission to update.
The updated submission.
curl -X PATCH \
'http://www.wixapis.com/form-submission/v4/submissions/e62e3011-55cf-4de3-a497-e097b52d86b7' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"submission": {
"id": "e62e3011-55cf-4de3-a497-e097b52d86b7",
"seen": true
}
}'
{
"submission": {
"id": "e62e3011-55cf-4de3-a497-e097b52d86b7",
"formId": "e62e3011-55cf-4de3-a497-e097b52d86b8",
"namespace": "wix.form_app.form",
"status": "PENDING",
"submissions": {
"first_name": "Adam",
"last_name": "Fisher"
},
"submitter": {
"memberId": "4b42fb49-8c77-4128-859c-8247756f68ef"
},
"seen": true,
"revision": 1,
"createdDate": "2019-10-30T17:22:10.299Z",
"updatedDate": "2019-10-30T17:22:10.299Z"
}
}
There is 1 error with this status code:
See the entire list and learn more about Wix errors.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Note: The Form Submission API only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms
is installed on the site.
Confirms a submission.
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 Update Submission endpoint.
You can only call this method when authenticated as a Wix app or Wix user identity.
Submission ID to confirm.
The confirmed submission.
curl -X POST \
'http://www.wixapis.com/form-submission/v4/submissions/e62e3011-55cf-4de3-a497-e097b52d86b7/confirm' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>'
{
"submission": {
"id": "e62e3011-55cf-4de3-a497-e097b52d86b7",
"formId": "e62e3011-55cf-4de3-a497-e097b52d86b8",
"namespace": "wix.form_app.form",
"status": "CONFIRMED",
"submissions": {
"first_name": "Adam",
"last_name": "Fisher"
},
"submitter": {
"memberId": "4b42fb49-8c77-4128-859c-8247756f68ef"
},
"seen": false,
"revision": 1,
"createdDate": "2019-10-30T17:22:10.299Z",
"updatedDate": "2019-10-30T17:22:10.299Z"
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Note: The Form Submission API only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms
is installed on the site.
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.
To learn about working with Query endpoints, see API Query Language, Sorting and Paging, and Field Projection.
You can only call this method when authenticated as a Wix app or Wix user identity.
Query options.
Whether to return only your own submissions. If false
, returns all submissions based on query filters.
The retrieved Submissions.
Paging metadata.
curl -X POST \
'http://www.wixapis.com/form-submission/v4/submissions/namespace/query' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"query": {
"filter": {
"formId": "e62e3011-55cf-4de3-a497-e097b52d86b8",
"namespace": "wix.form_app.form"
}
},
"onlyYourOwn": true
}'
{
"submissions": [
{
"id": "e62e3011-55cf-4de3-a497-e097b52d86b7",
"formId": "e62e3011-55cf-4de3-a497-e097b52d86b8",
"namespace": "wix.form_app.form",
"status": "PENDING",
"submissions": {
"first_name": "Adam",
"last_name": "Fisher"
},
"submitter": {
"memberId": "4b42fb49-8c77-4128-859c-8247756f68ef"
},
"seen": false,
"revision": 1,
"createdDate": "2019-10-30T17:22:10.299Z",
"updatedDate": "2019-10-30T17:22:10.299Z"
}
],
"metaData": {
"count": 1,
"cursors": {},
"hasNext": false
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Note: The Form Submission API only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms
is installed on the site.
Counts the number of submissions belonging to the specified forms.
You can only call this method when authenticated as a Wix app or Wix user identity.
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.
List of statuses of submissions which should be taken into count Default: CONFIRMED, PAYMENT_WAITING, PAYMENT_CANCELED
Forms submission count.
curl -X POST \
'http://www.wixapis.com/form-submission/v4/submissions/count' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"formIds": [
"e62e3011-55cf-4de3-a497-e097b52d86b8"
],
"namespace": "wix.form_app.form"
}'
{
"formsSubmissionsCount": [
{
"formId": "e62e3011-55cf-4de3-a497-e097b52d86b8",
"totalCount": 2,
"unseenCount": 1
}
]
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Note: The Form Submission API only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms
is installed on the site.
Retrieves a URL, generated by Media Manager, to allow clients to upload a file to a form for submission.
Form ID.
Name of file to upload.
Mime type of file to upload.
For example, 'image/png'
Url to upload file.
curl -X POST \
'http://www.wixapis.com/form-submission/v4/submissions/media-upload-url' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"form_id": "e62e3011-55cf-4de3-a497-e097b52d86b8",
"filename": "cats.mp4",
"mimeType": "video/mp4"
}'
{
"uploadUrl": "https://upload.wixmp.com/upload/eyJhbGciOiJfdddcCI6IkpXVCJ9.eyJqdGkiOiIqweFkM2NiMi0zYzQ4LTRjNDQtODBkNi0yYmEwMTUwZDM0OTEiLCJhdWQiOiJ1cm46c2VydmljZTp1cGxvYWQiLCJpc3MiOiJ1cm46c2VydmljZTp1c3NzY2OWZmMGQwNzRkN2YyLXN0YWdlIiwicGF0aCI6IjkzYTE5ZjZkLTkwZjUtNGFkZi04ZTEwLTk4Zj2UvZWZkYTdlZTYtZDFlZi00NzZjLWJmOTItZTYwNmEwYWMzNGQ0LXNjcmVlbi5wbmciLCJjYWxsYmFja1VybCI6Imh0dHBzOi8vd2l4bXAtMTY4YWExOTc3NzY2OWZmMGQwNzRkN2YyLmFwcHNwb3QuY29tL19hcGkvdjMvdXBsb2FkL2NhbGxiYWNrP3VwbG9hZFRva2VuPWV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpwYzNNaU9pSjFjbTQ2YzJWeWRtbGpaVHBtYVd4bExuVndiRzloWkNJc0ltRjFaQ0k2SW5WeWJqcHpaWEoyYVdObE9tWnBiR1V1ZFhCc2IyRmtJaXdpYzNWaUlqb2lkWsafdEp1T21Gd2NEbzNZVEk1TVdZek5ERmpaamswT1RrMU9UUmlNRFpsTjJVM09EbG1PV1ppTlNJc0ltbGhkQ0k2TVRZNE5qZ3hOREUwTWl3aVpYaHdJam94TmpnMk9EVTNNelF5TENKcWRHa2lPaUprTkRBMVlUQmpZekV3bkIwYUNJNklpODVNMkV4T1dZMlpDMDVNR1kxTFRSaFpHWXRPR1V4TUMwNU9HWTFZelZsT0RNeE5USXZOemt3WWpFNFpHUXRaV1UyTmkwME9EQmlMV0V4TTJRdE5qbGxZbUl3WXpKbE1qTmxMMlZtWkdFM1pXVTJMV1F4WldZdE5EYzJZeTFpWmpreUxXVTJNRFpoTUdGak16UmtOQzF6WTNKbFpXNHVjRzVuSWl3aVlXTnNJam9pY0hWaWJHbGpJaXdpYkdaaklqcDdJbUZuWlNJNk1qVTVNakF3TUN3aVlXTjBdfdhVzl1SWpvaVpXUWlPaUprWld4bGRHVXRNalU1TWpBd01DSjlMQ0pqYkdJaU9tNTFiR3g5Li1qdkg3VkN4U2N6UXZpM3U2MVJmSTg3WUY3YllKRGdlNWZqc21ZMk9WSEUiLCJhY2wiOiJwdWJsaWMiLCJtaW1lVHlwZSI6ImltYWdlL3BuZyJ9.z0G6bPu_K1qdoj9EK-6Lo_ZEpd2jTihSp6LEPBVqiXw"
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Note: The Form Submission API only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms
is installed on the site.
Marks form submissions as "seen".
This endpoint marks the submissions as if they were seen by the site owner. Only site collaborators with the Manage Submission permissions can mark submissions.
You can only call this method when authenticated as a Wix app or Wix user identity.
Submission IDs to mark as seen.
ID of the form which the submissions belongs to.
curl -X POST \
'http://www.wixapis.com/form-submission/v4/bulk/submissions/mark-as-seen' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"ids":["e62e3011-55cf-4de3-a497-e097b52d86b7"],
"formId": "e62e3011-55cf-4de3-a497-e097b52d86b8"
}'
undefined