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

When you create a Form Handler, you will map the fields of your pre-existing form to Prospect fields in Insightly. This will eliminate the need for manually entering data into Insightly after a Prospect has filled out your form.

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.

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.

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.


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.

Additionally, Insightly will track interactions with videos during a browsing session. Multiple videos can be embedded on a page.

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

Video events

When recording video interactions, Insightly will condense each event into one entry on the timeline tab. In the timeline tab, there will be one timeline entry for each video viewed within a browsing session by each visitor - not a separate timeline entry for each play and pause.

If a visitor interacts with a YouTube video, Insightly will capture:

  • The YouTube video’s name

  • The date of the event

  • The link to the video

  • Play, pause, and end events, with the timestamps in seconds


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.

    In the example above, 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?