> For the complete documentation index, see [llms.txt](https://docs.distro.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.distro.so/forms/existing-forms.md).

# Connect an existing form

Keep the form on your website and connect its successful submission to a Distro workflow.

The connection defines the captured fields, approved website origins, and whether Distro can show a scheduler or runs in the background.

## 1. Create the connection

In a workflow's **New form submission** trigger, select **Connect an existing form**.

Enter **Form name** and, for HTML capture, a **Form selector** that identifies exactly one form, such as `#demo-request`.

Add **Website origins**, one per line. Use exact origins such as `https://www.example.com`; do not include paths or wildcards. Approve staging separately if you test there.

## 2. Map the fields

Under **Form fields**, add each field used by the workflow.

Map the website's actual field name to a stable Distro answer key, choose its type, and set required behavior. An email field should use Email; a company-size comparison needs the intended numeric or choice type.

For custom nested SDK payloads, use the supported explicit source paths. A dot in an HTML field name does not automatically mean a nested object.

## 3. Choose the interaction

Open **Advanced form settings**.

| Setting                          | Use it for                                                                   |
| -------------------------------- | ---------------------------------------------------------------------------- |
| **HTML form**                    | A single HTML form connected to an explicit original-submission handler.     |
| **Explicit SDK submission**      | A provider callback or custom frontend that supplies fields after success.   |
| **Show a scheduler or redirect** | A browser journey that can present the workflow response.                    |
| **Run in the background**        | Server intake for CRM actions and notifications, without a visitor response. |

Saving the connection does not install it or start accepting submissions.

## 4. Publish and activate

Select the saved connection in the trigger, refresh its contract, and build the flow.

Publish the workflow. Reopen the connection's **Installation and submissions**, choose a compatible **Published workflow version**, and select **Activate this published version**.

Review the active workflow name and version. Use **Pause new submissions** and **Resume new submissions** when needed.

## 5. Install and verify

Use the connection's installation instructions. For browser mode, load `workflow_forms.js` on an approved origin and integrate the original form's confirmed success.

For provider forms, use the provider's real success callback. An ordinary button click or unconfirmed submit event is not proof that the original form succeeded.

See [Form SDK](/forms/sdk.md) for examples.

## After field changes

Save the new mappings, refresh the trigger, validate and publish the workflow, then activate the compatible version.

The active connection continues using its published contract until explicitly updated. Check it separately from the saved draft.

Use one Distro capture owner for each installation. Remove the old router capture when moving the form to the workflow integration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.distro.so/forms/existing-forms.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.