How to create a Form Handler

Form Handlers collect data from your forms, then automatically create or update records within Insightly Marketing.

 

How it works

Form Handlers eliminate the need to manually entering data into Insightly after a Prospect has filled out your form.

When you create a Form Handler, you will map the fields of your pre-existing form to Prospect fields in Insightly. You will need to create your own form outside of Insightly and add the Form Handler’s HTML from Insightly to the HTML of your own form.

SPAM

When a Form submission is received, Insightly will check the IP Address and the user. If five or more Form submissions are received in a five minute time period from the same IP Address and user, Insightly will not process the submission and it will be discarded. The submitter will receive an HTTP 500 error. This will occur even if the user is blank or null.

You can also utilize reCAPTCHA v3 to help web hosts to distinguish between human and automated access to websites. You will need to include the necessary JavaScript resource and add a few attributes to your HTML button. Read our reCAPTCHA v3 setup documentation to learn more.

This SPAM check occurs in Finish Action sequences for Redirect Links, Hosted Files, Form submissions, and List Emails.

HTML and JavaScript

Before you start, make sure you setup a Web Tracking Domain for your site. You will need to add the JavaScript tracking code to the HTML of your form on your website.

When you are finished creating your Form Handler, you can generate the form’s HTML. This code can then be added to a website and will contain all fields from the Form Handler, in order. From the record’s Actions dropdown, select Generate Form HTML.

When you are finished creating your Form Handler, Insightly will generate a Form Submit URL, which connects the form to the Form Handler. It can be found in the Form Handler record and cannot be edited.

This field also appears in the generated HTML. The field is formatted like this: <form name='insightly_form' data-form-id='4363' action='https://chloe.insightly.services/Forms/xxxxxx' method='post'>.

Do not edit or remove this from the HTML when adding it to your website, as this will disconnect the form from the Form Handler.

API

Insightly Form Handlers will only accept POST form submissions; "multipart/form-data" posts will not be accepted because Form Handlers cannot support file uploads.

Field validation

Field-level validation ensures that the values entered in your form by Prospects is in accordance with the requirements you configure. For example, if the Prospect attempts to leave a required field empty or enters a field incorrectly, they will be unable to submit the form successfully.

Here are some field validation options that Insightly supports:

  • Required fields - Requires specified fields to be entered before the form can be submitted.

  • Email Address - The Email field is the only required field for a form by default and it cannot be made optional. Every Prospect that submits a form must enter an Email Address.

    Additionally, users can implement one of the following validation requirements:

    • Email Address has a valid format - Checks that each email address contains the following: Recipient name, @ symbol, Domain name, Top-level domain. If this validation fails, the error "Please enter a valid email address" will appear.

      If you select this option, Insightly will only check this criteria.

    • Email Address has a valid mail server - Checks that the domain for the email address has valid MX records to receive email. If this validation fails, the error "Please enter a valid email address" will appear.

      If you select this option, Insightly will check that the Email Address has a valid format and that the Email Address has a valid mail server.

    • Email Address is a business email address - Checks that the domain for the email address does not match any free email providers and ISP email providers. If the email address comes from one of these types of providers, Insightly will reject it as it is not a business email address. If this validation fails, the error "Please enter a valid business email address" will appear.

      If you select this option, Insightly will check that the Email Address has a valid format, that the Email Address has a valid mail server and that the Email Address is a business email address.

  • Standard field consistency - When a field is added to the Form Handler, Prospects will be required to enter the field in the correct format (text, numeric, bit, datetime). Insightly will set the Data Type field based on the Field Type and cannot be edited.

  • Unsafe HTML - Reject any unsafe HTML tags and attributes to reduce the risk of a Prospect submitting malicious code.

  • reCaptcha - Setup reCaptcha to help web hosts to distinguish between human and automated form submissions.

Tracking events

Users can review their Prospect’s form interactions on Landing Pages or on a form setup on their own site from the Prospect record’s timeline tab.

Insightly will record information a Prospect entered on a form. These events will be recorded even if the Prospect does not submit a form. There aren’t any events recorded, however, that specify when a Prospect has made changes to the form.

Form events

When a visitor interacts with a form, Insightly will record one event in the visitor activity table for all the form fill events for that interaction for that specific visitor session.

When the timeline entry is clicked, information about how far the Prospect got in the form fill will appear.

If a visitor interacts with a form, Insightly will capture:

  • The Form Submission ID

  • The Visitor ID

  • The Prospect ID

  • The Date of Submission

  • The Database Action

  • The Method

  • The HTTP Response Code

  • The User IP Address

  • The User Agent

  • The Referrer

  • Form Data that was entered, such as an email address or a last name

 

How to create a Form Handler

  1. Select Forms from the navigation bar. Click New Form Handler.

  2. Enter your Form Handlers information. The Name field is required. If you select Specific URL from the Success Page or Error Page dropdowns, you will be required to enter a URL.

  3. If needed, edit the Duplicate Handling field. By default, it is set to update existing records instead of creating duplicate records.

  4. The Email field is the only required field for a Form. Click Add Form Field to add other fields for your Prospects. You can choose to make additional fields optional or required.
    When entering the Field Name, make sure it matches the field's name within the coding of your form. It needs to match the “name” property value of that corresponding element in the form on your website exactly. You cannot use spaces in the Field Name field.

    For example, the Field Name is ASSISTANT_NAME. You wouldn’t use Assistant Name because that is the Field Label, which is how the field appears within a record.

  5. Click Save.

 

How to add Finish Actions

Finish Actions allow you to add an automated activity that is triggered when someone submits your form.

For example, if you want to notify other users when a Form has been submitted by a Prospect, you could add a Finish Action to your Form record that gets triggered when a Form has been completed to send an email to any stakeholders.

Finish Actions will typically occur immediately after a form has been submitted and cannot be scheduled for a later date or time. They can, however, be assigned conditional criteria that will not allow the action to occur unless the submitted form has met the criteria that has been set. 

If you have multiple Finish Actions, they will only execute based on the Prospect's original field values. For example, say a Prospect started with a score of 5 and was updated to 10 as a result of the first action. If the section action were to execute for Prospects with a score of 10 or more, it would not execute because it was originally 5.

Finish actions will not execute if Insightly cannot identify the Prospect who completed the Form. The Prospect needs to have filled out and submitted a Form with the email address associated with their Prospect record.

  1. Go to the Finish Actions tab. Click Add Finish Action.

  2. Select an action from the dropdown.

  3. Enter the required fields. You can optionally add conditional criteria. For example, this Send Email action could require that the employee count needs to be greater than 10 for the action to be triggered.

  4. Click Save Finish Action.

 

Connecting the Form Handler to your form

When you are finished, you can add the Form Submit URL field to your API POST request.

Insightly Form Handlers will only accept POST form submissions; "multipart/form-data" posts will not be accepted because Form Handlers cannot support file uploads.

In the Submissions tab, users can review the Prospects who have filled out the form.

 

How to enable auto-filling Geographic Prospect data

Insightly can automatically fill the Country, State, and Canadian Province onto a Prospect record based on GeoIP information from a Form Post.

  1. Go to System Settings > Form Features.

  2. Click the checkbox to the right of Auto-Populate Prospect Address.

 

Learn more

Read these articles to learn more about Form Handlers:

Form Submission Report

How to edit a Form Handler

How to delete a Form Handler

Was this article helpful?