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.

Before you begin

  • 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.

Use cases

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.
Did this help?

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.

Did this help?

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 by Namespace

Did this help?

Submission Object


Form submission that was created or retrieved.

Properties
idstringRead-onlyformat GUID

Submission ID.


formIdstringformat GUID

ID of the form which the 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. Call Get Submission to retrieve the namespace.


statusstring

Status of the submission.


submissionsMap <string, Value>format map

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


createdDatestringformat date-time

Date and time the form submission was created.


updatedDatestringRead-onlyformat date-time

Date and time the form submission was updated.


revisionintegerRead-onlyformat int64

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.


submitterSubmitterRead-only

ID of the visitor that submitted the form.


seenboolean

Whether a site owner marked a submission as "seen".


extendedFieldsExtendedFields

Data extension object that holds users' and apps' fields.


orderDetailsOrderDetails

Order details.
Note: This object is only applicable when submittng a form in the Wix Payments app.


contactIdstringformat GUID

Contact ID of a site visitor who created the submission.

Did this help?

POST

Create 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.

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.

Permissions
Manage Submissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/form-submission-service/v4/submissions

Body Params
submissionSubmissionRequired

Submission to create.


captchaTokenstringminLength 1maxLength 3000

Captcha token.

Response Object
submissionSubmission

The created submission.

Create Submission Example 1
Request
cURL
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" } } }'
Response
JSON
{ "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" } }
Errors
400Invalid Argument

There is 1 error with this status code:

404Not Found

There is 1 error with this status code:

428Failed Precondition

There are 2 errors with this status code:

503Unavailable

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?

GET

Get 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.

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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Submissions
Read Submissions
Manage Orders
Read Orders
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/form-submission-service/v4/submissions/{submissionId}

Path Params
submissionIdstringRequired

ID of the submission to retrieve.

Response Object
submissionSubmission

The retrieved submission.

Get Submission Example 1
Request
cURL
curl -X GET \ 'http://www.wixapis.com/form-submission/v4/submissions/e62e3011-55cf-4de3-a497-e097b52d86b7' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "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" } }
Did this help?

DELETE

Delete 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.

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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Submissions
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/form-submission-service/v4/submissions/{submissionId}

Path Params
submissionIdstringRequired

ID of the submission to delete.

Query Params
permanentboolean

Whether to permanently delete a submission bypassing the trash bin.

Default: false


preserveFilesboolean

Whether to preserve files, associated with the submission. If the value is false, then the files are deleted after 210 days.

Response Object
Returns an empty object.
Delete Submission Example 1
Request
cURL
curl -X DELETE \ 'http://www.wixapis.com/form-submission/v4/submissions/e62e3011-55cf-4de3-a497-e097b52d86b7' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>'
Response
JSON
undefined
Did this help?

PATCH

Update 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.

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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Submissions
Learn more about app permissions.
Endpoint
PATCH
https://www.wixapis.com/form-submission-service/v4/submissions/{submission.id}

Path Params
submission.idstringRequired

Submission ID.

Body Params
submissionSubmissionRequired

Submission to update.

Response Object
submissionSubmission

The updated submission.

Update Submission Example 1
Request
cURL
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 } }'
Response
JSON
{ "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" } }
Errors
400Invalid Argument

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?

POST

Confirm 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.

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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Submissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/form-submission-service/v4/submissions/{submissionId}/confirm

Path Params
submissionIdstringRequired

Submission ID to confirm.

Response Object
submissionSubmission

The confirmed submission.

Confirm Submission Example 1
Request
cURL
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>'
Response
JSON
{ "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" } }
Did this help?

POST

Query 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.

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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Submissions
Read Submissions
Manage Orders
Read Orders
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/form-submission-service/v4/submissions/namespace/query

Body Params
queryQueryRequired

Query options.


onlyYourOwnboolean

Whether to return only your own submissions. If false, returns all submissions based on query filters.

Response Object
submissionsArray <FormSubmission>

The retrieved Submissions.


metadataMetadata

Paging metadata.

Query Submissions By Namespace Example 1
Request
cURL
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 }'
Response
JSON
{ "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 } }
Did this help?

POST

Count 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.

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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Submissions
Read Submissions
Manage Orders
Read Orders
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/form-submission-service/v4/submissions/count

Body Params
formIdsArray <string>Requiredformat GUIDminItems 1maxItems 100

Form IDs.


namespacestringRequiredminLength 10maxLength 50

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.


statusesArray <string>maxItems 4

List of statuses of submissions which should be taken into count Default: CONFIRMED, PAYMENT_WAITING, PAYMENT_CANCELED

Response Object
formsSubmissionsCountArray <FormSubmissionsCount>

Forms submission count.

Count Submissions Example 1
Request
cURL
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" }'
Response
JSON
{ "formsSubmissionsCount": [ { "formId": "e62e3011-55cf-4de3-a497-e097b52d86b8", "totalCount": 2, "unseenCount": 1 } ] }
Did this help?

POST

Get 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.

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.

Permissions
Manage Submissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/form-submission-service/v4/submissions/media-upload-url

Body Params
formIdstringRequiredformat GUID

Form ID.


filenamestringRequiredmaxLength 300

Name of file to upload.


mimeTypestringRequiredmaxLength 100

Mime type of file to upload.

For example, 'image/png'

Response Object
uploadUrlstringmaxLength 500

Url to upload file.

Get Media Upload URL Example 1
Request
cURL
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" }'
Response
JSON
{ "uploadUrl": "https://upload.wixmp.com/upload/eyJhbGciOiJfdddcCI6IkpXVCJ9.eyJqdGkiOiIqweFkM2NiMi0zYzQ4LTRjNDQtODBkNi0yYmEwMTUwZDM0OTEiLCJhdWQiOiJ1cm46c2VydmljZTp1cGxvYWQiLCJpc3MiOiJ1cm46c2VydmljZTp1c3NzY2OWZmMGQwNzRkN2YyLXN0YWdlIiwicGF0aCI6IjkzYTE5ZjZkLTkwZjUtNGFkZi04ZTEwLTk4Zj2UvZWZkYTdlZTYtZDFlZi00NzZjLWJmOTItZTYwNmEwYWMzNGQ0LXNjcmVlbi5wbmciLCJjYWxsYmFja1VybCI6Imh0dHBzOi8vd2l4bXAtMTY4YWExOTc3NzY2OWZmMGQwNzRkN2YyLmFwcHNwb3QuY29tL19hcGkvdjMvdXBsb2FkL2NhbGxiYWNrP3VwbG9hZFRva2VuPWV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpwYzNNaU9pSjFjbTQ2YzJWeWRtbGpaVHBtYVd4bExuVndiRzloWkNJc0ltRjFaQ0k2SW5WeWJqcHpaWEoyYVdObE9tWnBiR1V1ZFhCc2IyRmtJaXdpYzNWaUlqb2lkWsafdEp1T21Gd2NEbzNZVEk1TVdZek5ERmpaamswT1RrMU9UUmlNRFpsTjJVM09EbG1PV1ppTlNJc0ltbGhkQ0k2TVRZNE5qZ3hOREUwTWl3aVpYaHdJam94TmpnMk9EVTNNelF5TENKcWRHa2lPaUprTkRBMVlUQmpZekV3bkIwYUNJNklpODVNMkV4T1dZMlpDMDVNR1kxTFRSaFpHWXRPR1V4TUMwNU9HWTFZelZsT0RNeE5USXZOemt3WWpFNFpHUXRaV1UyTmkwME9EQmlMV0V4TTJRdE5qbGxZbUl3WXpKbE1qTmxMMlZtWkdFM1pXVTJMV1F4WldZdE5EYzJZeTFpWmpreUxXVTJNRFpoTUdGak16UmtOQzF6WTNKbFpXNHVjRzVuSWl3aVlXTnNJam9pY0hWaWJHbGpJaXdpYkdaaklqcDdJbUZuWlNJNk1qVTVNakF3TUN3aVlXTjBdfdhVzl1SWpvaVpXUWlPaUprWld4bGRHVXRNalU1TWpBd01DSjlMQ0pqYkdJaU9tNTFiR3g5Li1qdkg3VkN4U2N6UXZpM3U2MVJmSTg3WUY3YllKRGdlNWZqc21ZMk9WSEUiLCJhY2wiOiJwdWJsaWMiLCJtaW1lVHlwZSI6ImltYWdlL3BuZyJ9.z0G6bPu_K1qdoj9EK-6Lo_ZEpd2jTihSp6LEPBVqiXw" }
Did this help?

POST

Bulk 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.

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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Submissions
Read Submissions
Manage Orders
Read Orders
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/form-submission-service/v4/bulk/submissions/mark-as-seen

Body Params
idsArray <string>Requiredformat GUIDminItems 1maxItems 100

Submission IDs to mark as seen.


formIdstringRequiredformat GUID

ID of the form which the submissions belongs to.

Response Object
Returns an empty object.
Bulk Mark Submissions As Seen Example 1
Request
cURL
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" }'
Response
JSON
undefined
Did this help?