Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

# About the Form Submission Service Plugin 

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 [Wix Developers Center](fallback::https://dev.wix.com/apps/my-apps)) and the Form Submission service plugin. 

Learn more about [implementing a service plugin with Wix](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions).

## Before you begin

- The Form Submission service plugin only works with the Wix Forms app. Call [GetAppInstance](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::5a829a3f-423e-484e-80c5-b70320bf9383slug::get-app-instance*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance) 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](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/dev-center-setup/about-the-wix-dev-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 service plugin, 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](portalId::63e3acd8-2a9c-421d-8f92-d02930eeb59eresourceId::d4f80dee-1971-4f01-8d35-d2c6641f0954*fallback::https://dev.wix.com/docs/build-apps/developer-tools/extensions/about-extensions) tab in the Wix Developers Center.
1. Click **Create Extension** in the top right corner.
1. Filter by **Wix Forms** in the left menu. Then find **Form Submission** and click **Create**.
1. 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: <ul> <li> Wix Forms: `wix.form_app.form` </li> <li> Wix Pricing Plans: `wix.pricing_plans.v1.custom_form` </li> <li> Wix Online Programs: `wix.achievements.quizzes.v1.quiz` </li> </ul> |
| `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 Service Plugin: 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 service plugin integration.

## Validate an email field

1. A site visitor enters an email address into a form field and submits the form.
1. Wix sends a [Validate Submission](fallback::https://dev.wix.com/docs/rest/crm/forms/form-submission-service-plugin/validate-submission) service plugin request to your app.
1. 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:

    ```json
        {
            "validationResult": 
            {
                "errors": 
                [
                    {
                        "errorPath": "submission.submissions.email",
                        "errorMessage": "Wrong email format",
                        "params": {},
                        "useCustomErrorMessage": true
                    }
                ]
            }
        }
    ```

1. The email field is highlighted on the form, notifying the site visitor that the email is invalid.
1. After this validation, the site visitor corrects the email and submits the form.
1. Again Wix sends a [Validate Submission](fallback::https://dev.wix.com/docs/rest/crm/forms/form-submission-service-plugin/validate-submission) service plugin request to your app.
1. 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.
1. Wix sends a [Validate Submission](fallback::https://dev.wix.com/docs/rest/crm/forms/form-submission-service-plugin/validate-submission) service plugin request to your app.
1. 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:

    ```json
        {
            "validationResult": 
            {
                "errors": 
                [
                    {
                        "errorPath": "submission.count.forbidden",
                        "errorMessage": "Form submitted more than 1 time",
                        "params": {},
                        "useCustomErrorMessage": true
                    }
                ]
            }
        }
    ```

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

# Form Submission Service Plugin: Errors

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

## Validate Submission Errors

The [Validate Submission](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::79dae5de-949f-4f57-a5a4-670c05dbb88dslug::submission-extension-v4/validate-submission*fallback::https://dev.wix.com/docs/rest/api-reference/wix-forms/form-submission-spi/submission-extension-v4/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. |

value

Int64Value

values

ListValue

NullValue

StringValue

fields

Struct

nanos

seconds

Timestamp

Value

boolValue

listValue

nullValue

numberValue

stringValue

structValue

kind

Extended field data. Each key corresponds to the namespace of the app that created the extended fields.
The value of each key is structured according to the schema defined when the extended fields were configured.

You can only access fields for which you have the appropriate permissions.

Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields).

namespaces

ExtendedFields

this message is not directly used by any service,
it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform.
e.g. SPIs, event-handlers, etc..
NOTE: this context object MUST be provided as the last argument in each Velo method signature.

Example:
```typescript
export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) {
...
}
```

[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code.

currency

An object that describes the identity that triggered this request.

instanceId

A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`.

languages

A unique identifier of the request. You may print this ID to your logs to help with future debugging and easier correlation with Wix's logs.

requestId

Context

identityType

IdentificationData

IdentityType

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

appId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

alternativeUris

URI that will be used by the host to call the implementer. The path-suffix defined on the method will be appended to it

baseUri

SpiBaseUri

absolute uri that will be used by the host to call that method. The path-suffix mapped from the method http option will NOT be appended to this URI. For TPAs. it must be https

absoluteUri

name of the method as it appears in the proto

methodName

AlternativeUri

Form submission that was created or retrieved.

Date and time the form submission was created.

createdDate

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

ID of the form which the submission belongs to.

formId

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.

namespace

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

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.

revision

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

seen

Status of the submission.
- `PENDING`: A submission is created, but has not yet been recorded in the Wix Forms collection.
- `PAYMENT_WAITING`: A form submission requiring payment is created.
- `PAYMENT_CANCELED`: An order of a form submission is canceled.
- `CONFIRMED`: A submission is recorded in the Wix Forms collection.

status

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

submissions

ID of the visitor that submitted the form.

Date and time the form submission was updated.

updatedDate

FormSubmission

ID of the checkout related to submission (only applicable if a form has payments).

checkoutId

itemSubtotal

number

ID of the order related to submission (only applicable if a form has payments).

orderId

OrderDetails

SubmissionStatus

Submitter

applicationId

userId

visitorId

submitter

URI where the service plugin Implementer is deployed

namespaceConfigs

FormSubmissionSpiExtensionConfig

Targeted namespace, with what submissions should trigger defined methods.

submissionValidationEnabled

FormsSubmissionsExtensionNamespaceConfig

SubmissionErrorType

Path indicating the source of the error, such as `form.fields.target`.

errorPath

params

SubmissionValidationError

Custom error message. The message is displayed instead of an error type.

customErrorMessage

errorType

errorMessage

Whether to create or update the submission.

actionType

ValidateSubmissionRequest

ActionType

UpdateOptions

Data for updating an existing submission.

actions

List of validation errors. 
If there are no validation errors, returns an empty array.

errors

ValidateSubmissionResponse

SPI that allows provide additional actions on existing submission namespaces.

> **Note:** The Form Submission service plugin only works with the Wix Forms app. Call [GetAppInstance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance) 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.

Validate Submission

Permission Scopes