> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms SDK

> How to send form submissions programmatically through the Conversion Forms SDK

The Forms SDK allows you to send submissions programmatically to Conversion, in case your forms are custom built on your website.

## Forms SDK Script

Here is the Forms SDK JavaScript snippet, which needs to appear on each website page where you are using any Conversion form:

```javascript theme={null}
{/*  Add the Conversion Forms SDK script to your website  */}
<script src="https://forms.conversion.ai/script.js"></script>
```

You can place this script anywhere on the webpage (in the `head` or `body`), so long as it loads.

<Note>
  Each form will expose a code snippet that includes the Forms SDK script, but only one script is needed per page.
</Note>

## Using the Forms SDK

The following sample JavaScript snippet shows how to send submissions programmatically using the Forms SDK:

```javascript highlight={25-33} theme={null}
<!-- Add the Conversion Forms SDK script to the page -->
<script src="https://forms.conversion.ai/script.js"></script>

<script>
// Optional utility to access fields by their names
const FORM_FIELDS = {
  email: "<CONVERSION_FIELD_ID>",
  links: "<CONVERSION_FIELD_ID>",
};

const form = document.getElementById("<YOUR_FORM_ID>");

form.addEventListener("submit", async (event) => {
  event.preventDefault();

  const formData = new FormData(form);
  // Keys on `data` match the `name` attribute of each form input,
  // e.g. <input name="email" /> is read as data.email
  const data = Object.fromEntries(formData.entries());
  
  // For debugging:
  console.log("Form data:", data);

  try {
    const submitted = await window.ConversionFormsV1?.submit(
      "<CONVERSION_FORM_ID>",
      // Must be an object of key-value pairs, where keys are
      // form field identifiers and values are field values
      {
        [FORM_FIELDS.email]: data.<YOUR_FORM_INPUT_NAME>,
        [FORM_FIELDS.links]: data.<YOUR_FORM_INPUT_NAME>,
      }
    );

    if (submitted) {
      console.log("Conversion form submitted successfully");
    } else {
      console.warn("Conversion form submission was rejected");
    }
  } catch (error) {
    console.error("Error submitting Conversion form:", error);
  }
});
</script>
```

<Tip>
  Replace the following placeholders:

  * `<CONVERSION_FORM_ID>` with your Conversion form ID
  * `<CONVERSION_FIELD_ID>` with your Conversion form field IDs
  * `<YOUR_FORM_ID>` with the id of your `<form>` element
  * `<YOUR_FORM_INPUT_NAME>` with your form `<input>` element's name attribute
</Tip>

Steps to send submissions programmatically:

<Steps>
  <Step title="Create a new Conversion form">
    First, [create a new Conversion form](/product-docs/forms/dashboard/overview) in the dashboard and configure the fields you want to send over.
  </Step>

  <Step title="Add the Forms SDK script">
    Make sure the Forms SDK script above appears on the webpage with your form.
  </Step>

  <Step title="Define a helper object">
    Define a helper object to store the field IDs for each field. These IDs are used to reference field data in your code.
  </Step>

  <Step title="Wait for a form submission">
    Add an event listener to your form that listens for the `submit` event.
  </Step>

  <Step title="Call ConversionFormsV1.submit">
    Pass the form fields by field ID into `ConversionFormsV1.submit()`.

    <Info>
      If an email address is not passed through a form, it will not be mapped to or create a contact.
    </Info>
  </Step>

  <Step title="Check if submission was successful">
    `ConversionFormsV1.submit` will return whether the submission was successful.

    <Warning>
      If any of the submitted fields failed field validation, the submission will not be successful.
    </Warning>
  </Step>
</Steps>

## Debugging failed submissions

If `submit()` fails and returns "false," you can see details about why the form submission failed in the API response to `forms.conversion.ai`, located under the "Network" developer tab

```json theme={null}
// Sample error response
{
    "error": {
        "code": "INVALID_SUBMISSION",
        "properties": {
            "errors": {
                "cdf09568-4d5b-499d-9387-c0310f308b56": [
                    "Email address required"
                ],
                "0ab6a659-e651-442e-b1cc-42b68774c4d2": [
                    "Field required"
                ],
                "6b83733a-7f64-40bf-9688-18a54244ceb5": [
                    "Field required"
                ]
            }
        }
    }
}
```