> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Wix Forms Integration

## Article: Wix Forms Integration

## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/bookings/wix-forms-integration.md

## Article Content:

# Work with Wix Forms to Create Services and Bookings

Customers are required to complete the [booking form](https://support.wix.com/en/article/wix-bookings-creating-and-setting-up-your-booking-forms)
when signing up for a service. By default, all services use a standard booking
form. You can create custom booking forms by adding fields, removing fields, or
marking fields as required.

This article covers [booking forms](#booking-forms) for capturing customer details during checkout, and [intake forms](#intake-forms) for collecting waivers or consents before the scheduled service.

<blockquote>

As of January 31, 2025, Wix Bookings integrates with the [Wix Forms APIs](https://dev.wix.com/docs/rest/crm/forms/introduction.md)
to provide form functionality in a standardized way across all Wix solutions.

<details>
  <summary>Changes to the booking object</summary>
  
  The integration of Wix Forms APIs into Wix Bookings has introduced several changes to the [booking object](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/introduction.md).
  
  - **New fields*:
    - `formSubmissionId`: Unique ID of the [form submission](https://dev.wix.com/docs/rest/crm/forms/form-submissions/introduction.md)
      associated with the booking.
    - `formId`: Unique ID of the [booking form](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/introduction.md)
      belonging to the relevant service.
  - *Deprecated field*: The `additionalFields` array that stores data from the filled-out
    booking form is deprecated and will be removed on September 30, 2025. When [creating a booking](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md),
    specify the submitted booking form data in `formSubmission` instead of
    `booking.additionalFields`. Contact details from fields belonging to the
    default booking form are saved in the booking's `contactDetails`, while all
    other values aren't saved on the booking object. See the
    [default booking form](#default-booking-form-fields) for more details.
</details>
</blockquote>

## Booking forms

Due to the integration with Wix Forms APIs, you can create booking forms with a
wider variety of field types, including text, dropdowns, file uploads,
signatures, dates, and numbers. This functionality comes built-in with Wix
Forms.

Use the following APIs to manage booking forms and submitted data:

- [Forms API](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/introduction.md):
  Manage which fields are included in a custom booking form, including which ones customers must fill out while booking.
- [Services API](https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/introduction.md):
  Manage which booking form is connected to a service.
- [Form Submissions API](https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/introduction.md):
  Retrieve and manage data submitted by customers during the booking process.
- [Bookings API](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-writer-v2/introduction.md):
  Retrieve and manage the customer's `contactDetails` submitted in default booking form fields.

## Default booking form fields

When [creating a custom booking form](#create-a-new-service-with-a-custom-booking-form)
you need to clone the default booking form, which includes the following fields.

| Field name | Customer input required | Notes |
|-----|-----|-----|
| `firstName` | Required | |
| `lastName` | Required |  Can be removed in custom booking forms. |
| `email` | Required | Wix Bookings checks the format of the provided email address, but not whether it actually exists. |
| `phone` | Required | Wix Bookings checks the format of the provided phone number, but not whether it actually exists. |
| `address.country` | [Conditionally required](#conditionally-required-fields) | In [ISO 3166-2 code](https://en.wikipedia.org/wiki/ISO_3166-2) format. |
| `address.subdivision` | [Conditionally required](#conditionally-required-fields) | |
| `address.city` | [Conditionally required](#conditionally-required-fields) | |
| `address.postalCode` | [Conditionally required](#conditionally-required-fields) | |
| `address.streetName` | [Conditionally required](#conditionally-required-fields) | |
| `address.streetNumber` | [Conditionally required](#conditionally-required-fields) | |
| `address.addressLine` | Not required | Can be removed in custom booking forms. |
| `address.addressLine2` | Not required | Can be removed in custom booking forms. |

### Conditionally required fields

Customers are required to provide an address when booking a service at a
location that isn't associated with the business, such as their home or office.
Depending on the specified country, subdivision and/or postal code may not be
required.

You can remove the entire `address` object in custom booking forms if the [service](https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/introduction.md)
doesn't support `CUSTOMER` locations. Additionally, you can always remove
`address.addressLine` and `address.addressLine2` in custom booking forms,
even if the service supports booking at a `CUSTOMER` location.

## Booking form sample flows

You could create a new service with a custom booking form, create a new booking
with a filled-out booking form, or retrieve a booking's submitted booking form.

### Create a new service with a custom booking form
 You can follow these steps to create a new [service](https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/introduction.md)
and its associated custom booking form.

To set up a booking form:

1. Call Wix Forms' [Clone Form](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/clone-form.md) with `formId` set to `00000000-0000-0000-0000-000000000000`.
The cloned form inherits the `wix.bookings.v2.bookings` namespace from the source form. Save the ID of the returned form.
1. Call Wix Forms' [Update Form](https://dev.wix.com/docs/rest/crm/forms/form-schemas/update-form.md)
   to add additional, custom fields to the form, or to remove optional
   default fields. Make sure to set `fields.validation.required` appropriately.
1. Call Wix Bookings' [Create Service](https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/create-service.md). Specify the form ID in `service.form.id`.

### Create a booking with a filled-out booking form

You can follow these steps to create a new booking and submit its
booking form on behalf of the customer.

To create a booking:

1. Call Wix Bookings' [Query Services](https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/query-services.md)
   and display the services to the customer.
1. For the selected service, save `form.formId`.
1. Call Wix Forms' [Get Form Summary](https://dev.wix.com/docs/rest/crm/forms/form-schemas/get-form-summary.md).
   Make sure to specify the form ID.
1. Construct a valid JSON object based on the returned data. Make sure to use
   the exact values from `formSummary.fields.target` as keys in the JSON object.
   For example:

   ```json
   {
     "firstName": "Michaela",
     "lastName": "Docekalova",
     "phone": "+15554128513",
     "email": "Michaela.Docekalova@example.com"
   }
   ```

1. Call Wix Bookings' [Create Booking](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md).
    Specify the constructed JSON object in `formSubmission`.
1. Listen to Wix Bookings' [Booking Confirmed](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-writer-v2/booking-confirmed.md)
   and save `booking.formSubmissionId`.

<blockquote class="tip">

__Tip:__
To replace a booking's form submission with a new one, use [Set Booking Submission ID](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-writer-v2/set-booking-submission-id.md).

</blockquote>

### Retrieve a submitted booking form

You can follow these steps to retrieve the submitted booking form for a specific
booking.

To retrieve a submitted booking form:

1. Optional: If your use case requires more filters than supported in Wix Forms'
   [Query Submissions by Namespace](https://dev.wix.com/docs/rest/crm/forms/form-submissions/filter-and-sort.md#form-submissions-supported-filters-and-sorting),
   call Wix Bookings' [Query Extended Booking](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-reader-v2/query-extended-bookings.md)
   with the relevant query `filter`.
   For example, you could filter by booking `id` or `status`. We strongly recommend
   including `startDate` in any filter you specify to ensure optimal API performance.
1. Call Wix Forms' [Query Submissions by Namespace](https://dev.wix.com/docs/rest/crm/forms/form-submissions/query-submissions-by-namespace.md).
   Always filter `namespace` by `wix.bookings.v2.bookings` while setting additional
   query `filters` as required. For example, also filter by the list of form IDs
   retrieved from Query Extended Bookings.

## Intake forms

You can require or encourage customers to complete intake forms before the scheduled service. Intake forms collect additional information such as health waivers, liability releases, or consent forms with expiration tracking.

Use the following APIs to manage intake forms with Bookings:

- [Intake Forms API](https://dev.wix.com/docs/api-reference/crm/forms/other-services/intake-forms/intake-forms/introduction.md):
  Manage intake forms with expiration periods and generate shareable submission links.
- [Intake Form Submissions API](https://dev.wix.com/docs/api-reference/crm/forms/other-services/intake-forms/intake-form-submissions/introduction.md):
  Query, track, and manage intake form submissions.
- [Booking Policies API](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/introduction.md):
  Connect intake forms to services through booking policies.

## Intake form sample flows

You could create and connect an intake form to a service, or verify that a customer completed a required intake form before an appointment.

### Create and connect an intake form to a service

You can create an intake form and connect it to a service. You can require the form before booking, which blocks checkout until completed, or send it after booking as optional.

To set up an intake form for a service:

1. Call Wix Forms' [Create Form](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/create-form.md).
   Specify `"namespace": "wix.waivers.forms"` and include at least these `formFields`: `firstName`, `email`, and `signature`.
   Set `pii: true` and `required: true` in `inputOptions` for each of these form fields.
   Save the returned form ID.
1. Optional: Call [Update Intake Form Expiration Period](https://dev.wix.com/docs/api-reference/crm/forms/other-services/intake-forms/intake-forms/update-intake-form-expiration-period.md) with the form ID.
   Specify your desired `expirationPeriodInMonths`. For example, `12` for annual forms.
1. Call [Get Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/get-service.md) with the service ID.
   Save `bookingPolicy.id` from the response.
1. Call [Get Booking Policy](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/get-booking-policy.md) with the policy ID.
   Save `revision` from the response.
1. Call [Update Booking Policy](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/update-booking-policy.md) with:
   - `revision`: The saved revision.
   - `intakeFormPolicy.enabled`: `true`.
   - `intakeFormPolicy.formId`: Your intake form ID.
   - `intakeFormPolicy.timing`: For example, `AFTER_BOOKING`.
   - `intakeFormPolicy.completionRequirement`: For example, `OPTIONAL`.

### Verify intake form completion

Before an appointment, you can verify that the customer has a valid intake form submission.

To verify intake form completion:

1. Call [Get Event](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/get-event.md) with the event ID.
   Save `externalScheduleId` that maps to the service ID and `contactId` from `participants`.
1. Call [Get Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/get-service.md) with the service ID.
   Save `bookingPolicy.intakeFormPolicy.formId` from the response.
1. Call [List Intake Form Data By Contacts](https://dev.wix.com/docs/api-reference/crm/forms/other-services/intake-forms/intake-form-submissions/list-intake-form-data-by-contacts.md) with the contact ID and intake form ID.
1. Check if `mostRecentSubmission` exists with `status` of `VALID`, `EXTENDED`, or `EXEMPT`.
1. If no valid submission exists, call [Create Customer Submission Link](https://dev.wix.com/docs/api-reference/crm/forms/other-services/intake-forms/intake-forms/create-customer-submission-link.md) with the contact ID and intake form ID.
   Send the generated URL to the customer via email or SMS.

## See also

- Learn more about how business owners can customize
  [booking forms](https://support.wix.com/en/article/customizing-your-booking-forms).
- Learn more about the [Intake Forms app](https://support.wix.com/en/article/wix-apps-adding-and-setting-up-the-wix-waivers-and-intake-forms-app).