About the Form Submission SPI

As a provider of form submission services, you can integrate your service with Wix's forms to allow site owners to request and use your services on their Wix sites. By integrating your service with Wix, the service validates and submits site visitor's form.

The integration is done via an app in the Wix App Market (created in the Wix Developers Center) and the Form Submission SPI.

Learn more about implementing an SPI with Wix.

Before you begin

• The Form Submission SPI is only available in Wix Studio and Editor X.
• The Form Submission SPI only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms is installed on the site.
• There are several apps that use forms. To validate form submission for a specific Wix app, configure your app in the Developers Center for that Wix app by defining the relevant namespace field in the extension. For example, the namespace for the Wix Forms app is "wix.form_app.form".

Use cases

Using the SPI, you can design your app to validate a form after a site visitor submits it, including:

• Field validations: Check if the email address is in the correct format or that the name contains only alphabetic characters.
• Prevent submission of invalid data: Disable the submit button until all fields are correctly filled out.
• Real-time feedback: Highlight the invalid fields.
• Prevent duplicate submissions: Check for duplicate submissions based on certain criteria and prevent site visitors from submitting the same form multiple times.

Configuration

To enable Wix to communicate with your app:

1. Go to the Extensions tab in the Wix Developers Center.
2. Click Create Extension in the top right corner.
3. Filter by Wix Forms in the left menu. Then find Form Submission and click Create.
4. Provide the following configuration:

Name	Type	Description
deploymentUri	string	Required. URI which Wix Forms calls to retrieve the validation. The URI consists of base URI and endpoint path. For example, "deploymentUri": "https://my-validations.com/v4/validateSubmission" where https://my-validations.com is a base and v4/validateSubmission is the endpoint path.
namespaceConfigs	Array of objects	A collection of Wix apps.
namespaceConfigs.namespace	string	The app which the form submissions belong to: Wix Forms: wix.form_app.form Wix Pricing Plans: wix.pricing_plans.v1.custom_form Wix Online Programs: wix.achievements.quizzes.v1.quiz
namespaceConfigs.submissionValidationEnabled	boolean	Whether to enable the submission validation in your app.

Terminology

Term	Definition
Submission	Data received when a site visitor submits a form.
Validation	Process that makes sure the information that the site visitor put into a form is correct and meets certain rules.
Form	Online interface that allows site visitors to input and submit data.

Form Submission SPI: Sample Use Cases & Flows

This article presents sample flows your app can support. You aren't limited to this exact flow, but it can be a helpful jumping off point as you plan your Submissions SPI integration.

Validate an email field

1. A site visitor enters an email address into a form field and submits the form.

2. Wix sends a Validate Submission SPI request to your app.

3. Your server validates the request. The email isn't valid, and the server sends an object containing the error.

   Example of a violation response from your app:

   Copy

   1
   {
   2
           "validationResult": 
   3
           {
   4
               "errors": 
   5
               [
   6
                   {
   7
                       "errorPath": "submission.submissions.email",
   8
                       "errorMessage": "Wrong email format",
   9
                       "params": {},
   10
                       "useCustomErrorMessage": true
   11
                   }
   12
               ]
   13
           }
   14
       }

4. The email field is highlighted on the form, notifying the site visitor that the email is invalid.

5. After this validation, the site visitor corrects the email and submits the form.

6. Again Wix sends a Validate Submission SPI request to your app.

7. Your server validates the request. The email is valid and the server sends an object containing an empty list.

Prevent duplicate submissions

1. A site visitor submits the same form again, which is permitted.

2. Wix sends a Validate Submission SPI request to your app.

3. Your server checks for a unique submission token and validates the request. The server finds the duplicate and returns an object containing error.

   Example of a violations response from your app:

   Copy

   1
   {
   2
           "validationResult": 
   3
           {
   4
               "errors": 
   5
               [
   6
                   {
   7
                       "errorPath": "submission.count.forbidden",
   8
                       "errorMessage": "Form submitted more than 1 time",
   9
                       "params": {},
   10
                       "useCustomErrorMessage": true
   11
                   }
   12
               ]
   13
           }
   14
       }

4. With this validation violation, the site visitor can't submit this form again.

Form Submission SPI: Errors

This articles outlines error messages that might be issued when calling the Form Submission SPI.

Validate Submission Errors

The Validate Submission SPI might issue the following error messages:

Error code	Error message
TYPE_ERROR	The type of the submitted value is invalid. For example, a number is submitted instead of string.
REQUIRED_VALUE_ERROR	The required field value is not provided.
UNKNOWN_VALUE_ERROR	The submitted value is unknown.
MAX_LENGTH_ERROR	The submitted value exceeds the maximum length.
MIN_LENGTH_ERROR	The submitted value doesn't reach the minimum length.
PATTERN_ERROR	The submitted text value is not applicable for the predefined pattern. For example, a phone number pattern is (000) 000-0000 and the site visitor entered (123)4567890.
FORMAT_ERROR	The submitted text value is not applicable for the standard format. For example, the email is entered without the @ symbol.
MAX_VALUE_ERROR	The submitted numeric value is too large.
MIN_VALUE_ERROR	The submitted numeric value is too small.
MULTIPLE_OF_VALUE_ERROR	The submitted numeric value does not evenly divide by the specified value. For example, the number doesn't divide by 3 without leaving a remainder.
MIN_ITEMS_ERROR	The submitted value array doesn't reach the required minimum number of items.
MAX_ITEMS_ERROR	The submitted value array exceeds the number of maximum items.
NOT_ALLOWED_VALUE_ERROR	The submitted value is not in the list of allowed values.
DISABLED_FORM_ERROR	The form is disabled.