As a provider of form submission service plugin (formerly SPI), 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 app dashboard) and the Form Submission service plugin.
Learn more about implementing a service plugin with Wix.
wix_forms
is installed on the site.namespace
field in the extension. For example, the namespace for the Wix Forms app is "wix.form_app.form"
.Using the service plugin, you can design your app to validate a form after a site visitor submits it, including:
To enable Wix to communicate with your app:
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:
|
formId | string | Form ID which submissions will be validated. This field is optional. If you won't provide the form ID, submissions from all forms in the defined app will be validated. |
namespaceConfigs.submissionValidationEnabled | boolean | Whether to enable the submission validation in your app. |
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. |
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 service plugin integration.
A site visitor enters an email address into a form field and submits the form.
Wix sends a Validate Submission service plugin request to your app.
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:
{
"validationResult": {
"errors": [
{
"errorPath": "submission.submissions.email",
"errorMessage": "Wrong email format",
"params": {},
"useCustomErrorMessage": true
}
]
}
}
The email field is highlighted on the form, notifying the site visitor that the email is invalid.
After this validation, the site visitor corrects the email and submits the form.
Again Wix sends a Validate Submission service plugin request to your app.
Your server validates the request. The email is valid and the server sends an object containing an empty list.
A site visitor submits the same form again, which is permitted.
Wix sends a Validate Submission service plugin request to your app.
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:
{
"validationResult": {
"errors": [
{
"errorPath": "submission.count.forbidden",
"errorMessage": "Form submitted more than 1 time",
"params": {},
"useCustomErrorMessage": true
}
]
}
}
With this validation violation, the site visitor can't submit this form again.
This article outlines error messages that might be issued when calling the Form Submission service plugin.
The Validate Submission service plugin 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. |
SPI that allows providing additional actions on existing submission namespaces.
Deployment URI where the endpoints are called. Wix Forms appends the endpoint path to the deployment URI.
For example, to call the Validate Submission endpoint at https://my-form-submissions.com/v1/validateSubmission
,
the deploymentUri
you provide here is https://my-form-submissions.com/
.
Namespace names.
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 service plugin only works with the Wix Forms app. Call GetAppInstance to confirm that the app named wix_forms
is installed on the site.
Validates a submission.
Validates a site visitor's form submission and returns any validation violations.
Site visitors can see the validation violations on their forms. For example, invalid fields are highlighted in red.
Submission to validate.
Whether to create or update the submission.
Data for updating an existing submission.
List of validation errors.
If there are no validation errors, returns an empty array.
curl -X POST \
'http://www.wixapis.com/form-submission/v4/submissions/validate' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"submission": {
"id": "e62e3011-55cf-4de3-a497-e097b52d86b7",
"formId": "e62e3011-55cf-4de3-a497-e097b52d86b8",
"namespace": "wix.form_app.form",
"status": "PENDING",
"submissions": {
"first_name": "J0hn",
"last_name": "Doe"
"fiend_list": ["Tom", "Sally", "Bob"]
},
"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"
},
"actionType": "CREATE",
"createOptions": {}
}'
{
"validationResult": {
"errors": [
{
"errorPath": "first_name",
"params": {},
"errorType": "TYPE_ERROR"
},
{
"errorPath": "fiend_list/2",
"params": {},
"custom_error_message": "Bob is not a friend"
}
]
}
}