FormHQ makes heavy use of Google Tag Managers dataLayer API. This guide will explain the various dataLayer variables available for use inside your GTM configuration.

FormHQ will emit a dataLayer event whenever a form is successfully submitted on the page where the FormHQ embed code is present in the following format:

  event: "FormHQ - Form Submit",
  event_category: "FormHQ",
  event_action: "[group_name]",
  event_label: "[form_name] - [form_id]",
  event_value: [group_value/form_value], 
  form: {
    name: "[form_name]",
    id: "[form_id]",
    value: [form_value]
    group: {
      name: "[group_name]",
      id: "[group_id]",
      value: [group_value]

Replacing all the [...] placeholders above – a real payload of data might look something like this:

  event: "FormHQ - Form Submit",
  event_category: "FormHQ",
  event_action: "Resource Download",
  event_label: "Whitepaper - How FormHQ Works - 12345",
  event_value: 0, 
  form: {
    name: "Whitepaper - How FormHQ Works",
    id: "12345",
    value: 0
    group: {
      name: "Resource Download",
      id: "12",
      value: 0

Let’s break each dataLayer key:value pair down one-by-one:

This is the Google Tag Manager event key that will be used inside of trigger conditions and eventually attached to the tags you would like to port the FormHQ event data into. This value can be customized inside of your FormHQ embed code by overriding the gtmEventName configuration variable if desired.

By default, FormHQ will set the event category parameter to a value of FormHQ. The default value can be customized inside of your FormHQ embed code by overriding the eventCategory configuration variable if desired.

If the submitted form is assigned to a group inside of FormHQ – the value for this parameter will be the group forms group name. If the form doesn’t have a group assigned to it – but exists inside of FormHQ, a value of No Group will be assigned. Finally, if the submitted form hasn’t been synced to the FormHQ database a value of Form Missing in FormHQ is assigned.

The event_label should be one of two things: The form’s native platform name + ID – OR – the native platform id. The form name is not present if the submitted form is not synced to the FormHQ database.

The value of this parameter will be either a positive integer inherited from the assigned group’s value – or – a value set directly on the form. If there is no value assigned on the group or the form – a value of 0 is used by default.

The form object contains properties for specific metadata of the form that was submitted. This object is helpful when you wish to craft your own unique event structures instead of the pre-built event action & labels provided. Note – this makes FormHQ highly compatible with GA4’s new event based data model where the category/action/label hierarchy no longer exists.

Using these variables inside of GTM

You can extract and use these values easily by creating custom dataLayer variables inside of your Google Tag Manager container.

FormHQ uses the version 2 dataLayer variable syntax, this means that if you wish to access nested values inside the a dataLayer property, you can do so using DOT syntax (e.g: See the example screenshot below:

GTM dataLayer variable naming conventions

We highly recommend prefixing your custom dataLayer variables with DL - and also including the structure of the variable being referenced. For example, if you setup a dataLayer variable to reference the a good name for that variable would be DL - Following this naming convention will help keep your variables organized and less mentally taxing.

Plans that grow
with your business

Pay per:
Starter $27/mo
Pro $47/mo
Free $0/mo
Connections 5 15 1
Sync Frequency Daily Every 4 Hours Manual Only
Groups help 25 40 10
Sort Rules help 10 20 Not Included
Project Users 5 10 2
Event Values help
Group Level Group & Form Level Not Included
Field Values help
Included Included Not Included
Payload Filter help
Included Included Not Included
Support Email Priority Email Not Included