Skip to main content

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.

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: 
{/*  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.
Each form will expose a code snippet that includes the Forms SDK script, but only one script is needed per page.

​
Using the Forms SDK

The following sample JavaScript snippet shows how to send submissions programmatically using the Forms SDK: 
<!-- 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>
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
Steps to send submissions programmatically:
1

Create a new Conversion form

First, create a new Conversion form in the dashboard and configure the fields you want to send over.
2

Add the Forms SDK script

Make sure the Forms SDK script above appears on the webpage with your form.
3

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.
4

Wait for a form submission

Add an event listener to your form that listens for the submit event.
5

Call ConversionFormsV1.submit

Pass the form fields by field ID into ConversionFormsV1.submit().
If an email address is not passed through a form, it will not be mapped to or create a contact.
6

Check if submission was successful

ConversionFormsV1.submit will return whether the submission was successful.
If any of the submitted fields failed field validation, the submission will not be successful.

​
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 
// 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"
                ]
            }
        }
    }
}