Form Handlers

A form handler collects data from a form on your website and creates or updates a Prospect in Marketing, removing the manual re-entry step.

It can be the form itself, or it can sit behind a form you already have, with your existing fields mapped onto Prospect fields.

On this page:

• Before you start
• Creating a form handler
• Generating the form HTML
• Connecting an existing form
• Spam protection
• Auto-filling geographic data
• Tracking form interactions
• Managing form handlers
• Finish actions
• Validation errors
• Error reference

Before you start

⚠️ Set up your Web Tracking Domain first, and add the JavaScript tracking code to the HTML of the form on your website. Without it, tracking does not work.

⚠️ Form handlers accept POST submissions only. multipart/form-data posts are rejected, because form handlers cannot support file uploads. A form with a file upload field will not work through a form handler.

Creating a form handler

1. Go to Forms and click New Form Handler.
2. Complete the Form Handler Information section.
3. Define the fields under Form Field Mapping.
4. Set visibility under Permissions.
5. Click Save, or Save & New.

Field mapping

Email is the only required field. Add Form Field adds more, each marked optional or required.

⚠️ Spaces are not allowed in a Field Name.

⚠️ When mapping to an existing form, the Field Name must exactly match the name property of the corresponding element in that form’s HTML. Not the label, not the id. An exact match on the name attribute.

Generating the form HTML

Insightly can generate an HTML version of the form containing every field from the form handler, in order, for adding to a website. Useful where the form needs design work or elements unrelated to Insightly.

Open the form handler record, click Actions, and select Generate Form HTML. The code appears in a popup to copy.

Actions Menu with Generate Form HTML Selected

Connecting an existing form

Insightly also creates a Form Submit URL for connecting a form you already have, rather than replacing it.

Insightly Form Handler Submit URL Location

Spam protection

Four separate mechanisms, and only one of them is optional.

Rate limiting

⚠️ Five or more submissions in five minutes from the same IP and user are discarded, and the submitter receives an HTTP 500 error. This happens even when the user is blank or null. The same check applies to finish action sequences on form submissions, redirect links, hosted files and list emails.

URLs in name fields

⚠️ A URL in the First Name or Last Name field discards the entire submission with an HTTP 500 error. This is a bot signature, but it also means a legitimate submission containing something URL-shaped in a name field is silently lost.

The honeypot field

A honeypot is a hidden field bots fill in and humans never see. Insightly discards any submission with a value in it, while still showing the bot the success message so it does not retry.

Add the field insightly_additional_field in the Form Field Mapping section. Generating the form HTML then produces:

<div style="position:absolute; left:-9999px; top: -9999px;">

<label for="insightly_additional_field">Comments</label>

<input type="text" id="insightly_additional_field" name="insightly_additional_field">

</div>

reCAPTCHA v3

Google’s reCAPTCHA distinguishes human from automated access. Marketing uses v3, which scores each interaction rather than challenging the visitor.

Scores run 0.0 to 1.0, where 1.0 is most likely legitimate traffic and 0.0 most likely a bot. Because it does not interrupt the visitor, it can run at any time without affecting conversion, and it improves as it sees more of both legitimate and abusive behavior on the site.

Setup:

1. Sign up for an API key pair at google.com/recaptcha/admin/create for your website. A key pair is a public or site key, used to run the service on the site, and a secret key, which authorizes communication between your backend and reCAPTCHA.
2. In Marketing, select the user profile, then System Settings.
3. Under Product Settings, select Form Features.
4. Enter the keys in Public Key and Secret Key under reCAPTCHA Settings and click Save Settings.
5. Enable Recaptcha Enabled when creating the form handler.

Insightly then adds the reCAPTCHA implementation to the generated JavaScript, visible through Actions > Generate Form HTML.

⚠️ Never share the secret key.

⚠️ reCAPTCHA is not supported on Landing Page forms. It works on form handlers embedded in your own site only, so a landing page form has the other three protections and not this one.

Auto-filling geographic data

Insightly can populate country, state and Canadian province on a Prospect record from the GeoIP information on a form submission.

Select the user profile, then System Settings, then Form Features under Product Settings, and enable Auto-Populate Prospect Address.

Auto-Populate Prospect Address Form Setting

Tracking form interactions

Form interactions are tracked on Marketing landing pages and on your own forms once a form handler is connected, and appear on the Prospect’s Timeline tab.

ℹ️ Events are recorded even if the Prospect does not submit the form, so partial fills are visible. Clicking the timeline entry shows how far through the form they got. Changes a Prospect makes to what they have already entered are not recorded as separate events.

One event is recorded per visitor session covering all form fill activity in that interaction. What gets captured:

• Form submission ID, visitor ID, Prospect ID
• Date of submission
• Database action, method, HTTP response code
• User IP address, user agent, referrer
• The form data entered, such as email address and last name

Managing form handlers

Edit, clone, change record owner and delete are reached from the three-dot menu in the list view or the Actions dropdown in an open record.

Actions Button in Form Handler View

Finish actions

Finish actions run automated activity when a form is submitted, such as emailing stakeholders on submission.

Add, edit and delete them from the Finish Actions tab on the form handler record, through the three-dot menu on each action. Reorder with Move Up in Order and Move Down in Order.

Reordering Finish Actions in Insightly CRM

The same three constraints apply as on hosted files and redirect links:

⚠️ Finish actions cannot be scheduled, they run immediately on submission. Conditional criteria are the only way to hold one back.

⚠️ Multiple finish actions all evaluate against the Prospect’s original field values, not the result of earlier actions in the same sequence. Chaining actions that depend on each other’s output does not work.

⚠️ Finish actions do not run for unidentified Prospects.

Validation errors

Submissions can fail validation for any of these reasons:

• A form field validation error
• A custom validation rule you defined
• A reCAPTCHA error
• Invalid content type
• Form handler not found
• Form data not found
• User data not found
• Invalid input characters
• Invalid form hash
• Exceeded submission limit, five or more in five minutes
• Permission denied, where the instance no longer has an active Marketing subscription

Error reference

For building a user-facing error page. Each error is what the query parameter reports, with the action that resolves it.