# About the Form Schemas API

The Form Schemas API allows you to create and manage form schemas. These are structural blueprints that define forms on Wix sites. A form schema specifies the fields, validation rules, layout, and behavior settings that determine how forms appear and function. For more information about how forms appear on a site, see [Wix Forms](fallback::https://support.wix.com/en/article/wix-forms-an-overview).

When working with the Forms APIs, you are always working with form schemas. For the sake of simplicity, the terms form and form schema are used interchangeably.

With the Form Schemas API, you can:

- Create custom form schemas with specific field types, validation rules, and layouts.
- Clone existing schemas to quickly replicate successful form designs.
- Update schema structure, field configurations, and display settings.
- Manage schema lifecycle including enabling, disabling, and organizing schemas by namespace.
- Configure advanced features like spam protection, submission limits, and post-submission actions.

Each app made by Wix that supports forms has its own unique identifier called a namespace. A form schema's `namespace` property defines which namespace it belongs to. 

Form schemas are used in apps made by Wix as blueprints for generating the forms they add to user's sites. For example, when user selects a form template in Wix Forms and adds it to their site, Wix Forms creates a new form using the corresponding form schema.

Each form schema belongs to a specific namespace which identifies the app that owns it. You can create form schemas in any namespace by specifying the namespace in your form schema's `namespace` property. For example, you can create an app that creates form schemas in the Wix Forms namespace. Wix Forms users will then be able to download your app and get access to your form schemas through the Wix Forms app.

[Form submissions](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/introduction) are recorded per form schema. A user may have multiple instances of forms on their site with the same form schema, but there is no distinction between these instances in the submissions.

> **Note:** While the names of the object and endpoints in this API say "Form", such as "Create Form", they're always referring to form schemas.

## Before you begin

It's important to note the following points before starting to code:

- Each form schema must belong to an app's namespace, which is assigned in the form schema's `namespace` property. To use your form schemas, the user must have their associated apps installed.


## Form deletion and the trash bin

You can delete form schemas by calling the [Delete Form](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/delete-form) method with the `formID`. This doesn't permanently delete the form schema, but instead moves it to the trash bin. 

Form schemas are kept in the trash bin for 90 days before they're permanently deleted. When a form schema is permanently deleted, all form submissions associated with that form schema are also deleted. 

Deleted form schemas aren't retrieved by standard methods, such as [Query Forms](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/query-forms), but can be retrieved with methods specifically intended for deleted form schemas, such as [Query Deleted Forms](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/query-deleted-forms).

## Namespaces of apps made by Wix

| App Name         | Namespace                                   |
|------------------|---------------------------------------------|
| Wix Pricing Plans    | `wix.pricing_plans.v1.custom_form`          |
| Wix Forms         | `wix.form_app.form`                         |
| Wix eCom             | `wix.ecom.v1.checkout`                      |
| Wix Quizzes          | `wix.achievements.quizzes.v1.quiz`          |
| Wix Bookings         | `wix.bookings.v2.bookings`                  |
| Wix Contacts         | `wix.contacts.v4.contact`                   |

## Use cases

- [Create a custom lead-capture form](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/sample-flows#create-a-custom-lead-capture-form)
- [Update an existing form with new fields](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/sample-flows#update-an-existing-form-with-new-fields)
- [Sync form data with an external application](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/sample-flows#sync-form-data-with-an-external-application)

## Terminology

- **Form schema:** The structural definition of a form, including its fields, layout, validation rules, and behavior settings.
- **Namespace:** A unique identifier for the app that owns the form schema.
- **Form field:** An individual input element within a form schema, such as for text, email, or dropdown options, and its associated validation and display properties.
- **Field validation:** Rules that determine what input is acceptable for each form field, including data type, format, and content requirements.
- **Limitation rule:** Settings that automatically disable form submissions when certain thresholds are reached, such as maximum submission count or deadline dates.
- **Post-submission trigger:** Automated actions that are executed after a form submission is received, enabling integration with other Wix services and external systems.
- **Submitter:** The end user filling out the form.

@sdk_package_setup

# Form Schemas: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful jumping off point as you plan your implementation.

### Create a custom lead-capture form

In this scenario, you're building an app that provides a specialized lead-capture form to integrate with an external CRM or a proprietary data system. This is useful for offering advanced customer management or marketing automation services.

To create a custom lead-capture form:

1. Call [Create Form](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/create-form) to build a new form schema on the user's Wix site. In your call, you can define all the necessary fields, such as 'Name', 'Email', 'Phone Number', and 'Inquiry'.
2. Store the `formId` that's returned in the response. You'll need to use this ID if you want to manage the form schema in the future.
3. Your app can now listen for form submission events using the [Form Submissions API](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/introduction). For example, when a site visitor submits the form, your app can receive the data through the [Submission Created](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/submission-created) event, which you can then process and send to your external CRM or database.

### Update an existing form with new fields

In this scenario, you're building an app that allows users to modify existing form schemas. For example, adding a "How did you hear about us?" dropdown to a contact form schema to gather more detailed marketing insights. Your app can provide the interface to make this change.

To add a new field to an existing form schema:

1. Call [List Forms](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms) to retrieve a list of all form schemas and present them to the user for selection.
2. Store the `formId` of the selected form schema.
2. Call [Get Form](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form) to retrieve the complete, current structure of that form schema.
3. In your app's UI, use the data from Get Form to display the form schema's current fields and allow the user to add, edit, or remove fields.
4. After the user saves their changes, call [Update Form](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/update-form), passing the new, updated form schema structure in the request body. The form schema on the site will be instantly updated.

### Sync form data with an external application

In this scenario, you're building an app that act as a bridge between Wix Forms and another system, such as a project management tool, a spreadsheet, or a custom database.

To sync form data:

1. First, create a new form schema using [Create Form](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/create-form) or let the user select an existing form schema using by calling [List Forms](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms) and presenting them the options to choose from. Then save the ID.
2. Using the ID from the selected or created form schema, implement an event listener in your app to receive notifications for events such as [Form Created](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-created), and [Form Updated](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-updated). When these events occur, use the information in the payload to update the form schema data in your external system.
3. Implement an event listener in your app to receive notifications for [Form Submission](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/introduction) events. When these events occur, check the `formId` in the payload to see if the event matches the ID of the form schema you created or selected in step 1. If it matches, use the information in the payload to create, delete, or update the form submission record in your external system.

# Form Schemas: Supported Filters and Sorting

The following table shows field support for filters and sorting for the form schema object:

| Field                                               | Supported Filters                                                              | Sortable |
|-----------------------------------------------------|--------------------------------------------------------------------------------| -------- |
| `id`                                                | `$eq`, `$ne`, `$in`, `$nin`                                                    | Sortable |
| `namespace`                                         | `$eq`, `$ne`, `$in`, `$nin`                                                    | Sortable |
| `createdDate`                                       | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$gt`, `$lt`, `$le`, `$ge`, `$nin` | Sortable |
| `updatedDate`                                       | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$gt`, `$lt`, `$le`, `$ge`, `$nin` | Sortable |
| `name`                                              | `$eq`, `$ne`, `$in`, `$nin`, `$startsWith`                                     | Sortable |
| `enabled`                                           | `$eq`, `$ne`                                                                   | Sortable |

**Related content:**
[API Query Language](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::a6026c51-be14-4ea6-a108-dcbc36b074fa*fallback::https://dev.wix.com/api/rest/getting-started/api-query-language),
[Query Forms](fallback::https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/query-forms)

Property	Filters	Sort
`id`	`$eq`, `$in`, `$ne`, `$nin`	Sort: `ASC`, `DESC`
`namespace`	`$eq`	Sort: `ASC`, `DESC`
`createdDate`	`$eq`, `$gt`, `$gte`, `$in`, `$lt`, `$lte`, `$ne`, `$nin`	Sort: `ASC`, `DESC`
`updatedDate`	`$eq`, `$gt`, `$gte`, `$in`, `$lt`, `$lte`, `$ne`, `$nin`	Sort: `ASC`, `DESC`
`properties.name`	`$eq`, `$ne`, `$nin`, `$in`, `$startsWith`	Sort: `ASC`, `DESC`
`name`	`$eq`, `$ne`, `$nin`, `$in`, `$startsWith`	Sort: `ASC`, `DESC`
`properties.disabled`	`$eq`, `$ne`	Sort: `ASC`, `DESC`
`enabled`	`$eq`, `$ne`	Sort: `ASC`, `DESC`
`fields.validation.predefined.format`	`$hasSome`	None
`tags.privateTags.tagIds`	`$hasAll`, `$hasSome`	Sort: `ASC`, `DESC`