Forms SDK

The Forms SDK is a lightweight JavaScript library that lets your website interact with Conversion forms programmatically. Use it to:

Submit a custom-built form on your website to Conversion
Listen for submissions from embedded Conversion forms
Set field values on embedded Conversion forms
Capture UTM parameters and other page context alongside submissions

Installation

Add the Forms SDK script to every page where you use a 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 exposes a code snippet that includes the Forms SDK script, but only one script is needed per page.

The Conversion pixel (website tracking script) is still required alongside the Forms SDK: it sets the tracking cookies that associate submissions with the visitor’s tracking ID. Without it, submissions are not linked to tracked visitors.

Finding your form and field IDs

The examples below reference two kinds of identifiers:

Form ID: shown in the form’s embed snippet and in the dashboard URL when the form is open.
Field IDs: listed in the Form fields table under your form’s Advanced settings, for both displayed and hidden fields.

Throughout the examples, a small helper object keeps field IDs readable:

// Optional helper to access fields by their readable names
const FORM_FIELDS = {
  email: "<CONVERSION_FIELD_ID>",
  utmSource: "<CONVERSION_FIELD_ID>",
};

Submitting a custom form

If your form is custom built on your website, ConversionFormsV1.submit() sends its submissions to Conversion. It takes your Conversion form ID and an object mapping field IDs to values, and returns whether the submission was accepted:

const submitted = await window.ConversionFormsV1.submit(
  "<CONVERSION_FORM_ID>",
  {
    [FORM_FIELDS.email]: "user@example.com",
  }
);

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

Step by step

Create a Conversion form

Create a form in the dashboard with an input for each value you want to send. The form must be Published to accept submissions.

Add the SDK script

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

Map your field IDs

Copy each field’s ID from the form’s Advanced settings into a helper object:

const FORM_FIELDS = {
  email: "<CONVERSION_FIELD_ID>",
  links: "<CONVERSION_FIELD_ID>",
};

Listen for your form's submit event

Read your form’s values when the visitor submits it. Keys on data match the name attribute of each input, e.g. <input name="email" /> is read as data.email:

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

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

  const formData = new FormData(form);
  const data = Object.fromEntries(formData.entries());
});

Call ConversionFormsV1.submit

Inside the listener, pass the values to Conversion keyed by field ID:

const submitted = await window.ConversionFormsV1.submit(
  "<CONVERSION_FORM_ID>",
  {
    [FORM_FIELDS.email]: data.email,
    [FORM_FIELDS.links]: data.links,
  }
);

Check whether the submission succeeded

submit() resolves to true when the submission was accepted.

If any of the submitted fields failed field validation, the submission will not be successful. See debugging failed submissions.

Complete example

<!-- Add the Conversion Forms SDK script to the page -->
<script src="https://forms.conversion.ai/script.js"></script>

<script>
// Optional helper to access fields by their readable 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);
  const data = Object.fromEntries(formData.entries());

  try {
    const submitted = await window.ConversionFormsV1.submit(
      "<CONVERSION_FORM_ID>",
      {
        [FORM_FIELDS.email]: data.email,
        [FORM_FIELDS.links]: data.links,
      }
    );

    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

What is included automatically

When available, the SDK automatically attaches the visitor’s tracking ID, session ID, page URL, and referrer to every submit() call, so submissions are attributed to the right contact and session without extra work.

Capturing UTM parameters

UTM parameters are not captured automatically. To store them with a submission, add a hidden field to your form for each parameter, then read the values from the page URL and pass them like any other field:

const FORM_FIELDS = {
  email: "<CONVERSION_FIELD_ID>",
  utmSource: "<HIDDEN_FIELD_ID>",
  utmCampaign: "<HIDDEN_FIELD_ID>",
};

const params = new URLSearchParams(window.location.search);

await window.ConversionFormsV1.submit("<CONVERSION_FORM_ID>", {
  [FORM_FIELDS.email]: data.email,
  [FORM_FIELDS.utmSource]: params.get("utm_source") ?? "",
  [FORM_FIELDS.utmCampaign]: params.get("utm_campaign") ?? "",
});

UTM parameters are usually only present on the landing page URL. If visitors navigate before submitting, store the values (e.g. in sessionStorage) when they first arrive and read them back at submission time.

For embedded Conversion forms, pass UTM values into hidden fields with a set-values message instead.

Working with embedded forms

Embedded Conversion forms render inside an iframe, and the Forms SDK script on the parent page keeps them connected: it resizes the iframe to fit the form and shares the visitor’s tracking context. You can also exchange messages with the iframe to react to submissions and update field values.

Your form’s Advanced settings generate these snippets pre-filled with your form and field IDs.

Listening for submissions

When an embedded form is submitted, it posts a conversion-forms message with the submitted event to the parent page. This is useful for firing analytics events or triggering your own UI:

window.addEventListener("message", (event) => {
  if (event.data?.type === "conversion-forms" && event.data.data?.eventName === "submitted") {
    const fields = event.data.data.fields || {};
    console.log("Form submitted:", fields);

    // Example of pulling specific values:
    // console.log("Email:", fields[FORM_FIELDS.email]);
  }
});

The fields object maps each field ID to its submitted value.

Setting field values

Send a set-values message to pre-fill visible fields or populate hidden fields (for example, with UTM parameters). Wait for the form’s conversion-forms-ping message so you know the form is ready:

window.addEventListener("message", (event) => {
  // Only handle messages from Conversion Forms
  if (event.data?.type !== "conversion-forms-ping" || event.origin !== "https://forms.conversion.ai") return;

  const params = new URLSearchParams(window.location.search);

  document.getElementById("<YOUR_FORM_ID>")?.contentWindow.postMessage({
    type: "conversion-forms",
    data: {
      eventName: "set-values",
      fields: {
        // Pre-fill a visible field
        [FORM_FIELDS.email]: "user@example.com",
        // Populate a hidden field, e.g. with a UTM parameter
        [FORM_FIELDS.utmSource]: params.get("utm_source"),
        // Remove a previously set value
        [FORM_FIELDS.utmCampaign]: null,
      }
    }
  }, "https://forms.conversion.ai");
});

To clear a previously set field, set its value to null.

Conditional fields

If your Conversion form uses conditional fields, the same visibility rules are enforced for SDK submissions: fields hidden for the visitor are never required, and values submitted for them are discarded.

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

Records

Emails

Workflows

Audiences

Forms

Content

Campaigns

Data Syncing

Unified Query Engine

Folders

Liquid

Tracking

Workspace Settings

GDPR

Installation

Finding your form and field IDs

Submitting a custom form

Step by step

Complete example

What is included automatically

Capturing UTM parameters

Working with embedded forms

Listening for submissions

Setting field values

Conditional fields

Debugging failed submissions

​Installation

​Finding your form and field IDs

​Submitting a custom form

​Step by step

​Complete example

​What is included automatically

​Capturing UTM parameters

​Working with embedded forms

​Listening for submissions

​Setting field values

​Conditional fields

​Debugging failed submissions

Installation

Finding your form and field IDs

Submitting a custom form

Step by step

Complete example

What is included automatically

Capturing UTM parameters

Working with embedded forms

Listening for submissions

Setting field values

Conditional fields

Debugging failed submissions