This guide walks through how to integrate embedded forms with Liine. It's intended for your web, marketing, or form building team. By the end, you'll know what what qualifies as an embedded form, it takes to integrate embedded forms, and how to integrate them.
What Is Form Integration for Embedded Forms?
Form Integration is a standard implementation path wherein you and your web team create, own, and operate your embedded web forms, and we work with your team to set up Liine downstream of your forms to capture submission data.
Embedded web forms are those forms that are hosted on a domain you control. This is distinct from platform-hosted forms – those forms confined to an ad platform/ecosystem such as Facebook/Meta or Google. We are able to integrate with platform-hosted forms, and much of the guidance here is relevant, but reach out to a Liine team member for clarification on integrating platform-hosted forms!
Both embedded and platform-hosted form integration is distinct from another implementation path, Managed Forms, where Liine creates, owns, and operates your forms.
This guide pertains to Form Integration for embedded forms. For questions or guidance on form integration with platform-hosted forms, reach out to Liine. Additionally, this guide does not pertain to Managed Forms, a separate implementation path.
Form Integration Requirements
To integrate your forms, you must be able to:
1. Send form data (via webhook / POST request) upon submission to a designated URL
2. Edit/control the fields in the data payloads sent
3. Ensure consistency of payload fields and structure
4. Create hidden fields on the form to be included in submission payloads, with the ability to customize placeholder text or otherwise edit specific HTML attributes
If your team can meet these four requirements, we can integrate forms into Liine optimally.
Supported Form Builders
We are able to integrate forms with the below list of form building platforms. Note, however, that your ability to integrate may depend on your tier within the form builder and additional fees may be required.
If your form builder appears on this list, please review the Requirements to ensure your team will be able to make the necessary adjustments.
If you don't see your form builder here or use a home-grown option, check the Requirements to see if integration may still be an option! So long as you meet those requirements, we can integrate your forms. If you're unsure, don't hesitate to reach. out to the Liine team.
Supported Form Builders:
GoHighLevel
Gravity Forms
Hubspot V4 forms (Updated form editor)
Your ability to integrate using a supported form builder may be dependent upon your tier within the form builder. Similarly, additional fees may be required in your form builder.
Form Integration: Implementation Steps
If you feel confident your team meets the Integration Requirements or see your form builder on our integration partners list, below are detailed steps for integrating your embedded forms with Liine. These steps will need to be actioned by your marketing, web, or form building team.
Prerequisite: Liine SDK Installation
For an integrated form to capture dynamic marketing data (Step 2), our Liine SDK snippet needs to be installed on the page the form lives on. As part of Step 0, we’ll confirm our snippet is in place once you share the form page URLs.
Step 0: Share Your Form Page URLs
If you haven’t already, share the URLs for the pages your forms will live on with the Liine team. We’ll review the pages for any potential complications. Certain page structures or elements, such as an iframe, call for special attention.
Step 1: Configure the Payload and Ensure Consistency
Step 1: Configure the Payload and Ensure Consistency
Configuring the correct form payload structure and ensuring consistency of that structure is paramount to integrating forms successfully. Liine must be able to rely on consistent field names and structure across payloads.
The final step in integrating forms is for the Liine team to map the incoming data. If these field names or locations change, our mapping breaks, and your form data will not appear in Liine as expected. Making unexpected payload changes or varying payloads from form to form are the most common pitfalls in form integration, so please be wary of this!
Flat Payload Structure
As a best practice, keep form payloads flat, not nested. Liine works most reliably when the fields of interest exist at the top level of the JSON payload. Once we receive sample submissions, we’ll confirm the structure and align with your team.
Liine Field Types: Standard and Custom
When ingesting form data, there are two types of fields in Liine: Standard and Custom.
Standard Fields participate across application UI and logic. These are the fields you'll see as column headers and/or filters. Certain of these are required to create an interaction in Liine.
Custom Fields appear in the FormFlow Details drawer for each form captured. They will not appear in filters or columns, but the team can find them in FormFlow. Your team is free to pass these in as they see fit.
Details below on passing both of these in to Liine.
Standard Fields
Standard fields are broken out in your Liine dashboard as columns in your Interaction Log and/or filters for your team to slice and dice your dashboard data on. These are included in Exports from your Interaction Log.
In each form payload, Liine expects the following Standard Fields, certain of which are required. These field names are case sensitive, and they need to be in the first level of your payloads. If your form payload is a nested JSON object with multiple levels, please move these to the first level of the object:
Field Name | Required | Value |
| Required | The lead’s whole name |
| Required | The lead’s phone number |
| Required | The lead’s email |
| Best Practice | The practice the lead is interested in visiting. Please align these values with the Locations you see in Liine, matching the strings exactly. |
| Best Practice | If your team isn't using Treatment Type in Liine, disregard this. This is your Liine Treatment Type, the treatment or service the lead is interested in. Similar to |
| Required | This value will contain our session GUID, used to enable dynamic marketing attribution. More on this in Step 2. This will come from Liine and never be a static, hard-coded value. |
A phone or email is the bare minimum Liine needs to create a form submission in your dashboard.
For location and division, if you're unsure of the exact string values to pipe in to Liine, reach out to your Liine team to get a list of those exact string values.
Custom Fields
Any data beyond those Standard Fields is considered a 'custom field.' Custom Fields are only reflected in the Details drawer of the form submission in FormFlow. Custom Fields do not appear in the Interaction Log or anywhere else in your dashboard, and they are not included in exports. By default, Custom Fields will be passed through to the Details drawer in FormFlow, but they'll be passed through however they are named and structured in the form payload.
For example, consider a question on your form such as 'How quickly are you seeking treatment?' If this is located in the first level of the payload and the question matches the field name in the payload, you'll find the question and its value nicely formatted in the FormFlow Details draw. If the question is passed in to the payload via an auto-generated unique identification string or nested in the payload, it won't come through nicely in the Details drawer, and we'll hide the field to keep your Details drawer clean.
💡 A Note on Consistency and Scaling
Consistency is the key to scalable form integrations. When every payload uses the same field names and structure, Liine can map new or updated forms seamlessly. Inconsistent or changing payloads are the most common cause of data gaps, so treat your established payload pattern as a contract – any variation requires coordination before launch or legwork in correcting unexpected changes.
Step 2: Capturing Dynamic Marketing Attribution
Step 2: Capturing Dynamic Marketing Attribution
With our SDK snippet in place on your site, every visitor is assigned a unique identifier for their current session. This is our ‘session GUID’ (globally unique identifier), a fixed length string of randomly generated alphanumeric characters in a consistent, 8-4-4-12 character block format:
xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx
To capture dynamic marketing attribution, our session GUID must be included in the form payload. There are three recommended options, detailed below, for including our session GUID in the form payload. Each option is a variation on injecting our session GUID into a dedicated hidden field on your form.
Regardless of the option chosen, you’ll need to:
Add a new custom field to your form.
Set the field to hidden, so users don’t see the field on the form.
Ensure the hidden field is included in the form payload.
In the form payload, include the value from the hidden form field in a payload field name called
__liine_session_guid. Refer to Step 1 for formatting this in the first level of the payload.
Options 1 and 2 require coordination with the Liine team. Option 3 is the most technically involved from your team but does not require coordination; it can be configured independently by your team.
Option 1: URL Query Parameter Method
In this option, for every visitor session:
We append the Liine session GUID to your site’s URL.
Your team pulls the session GUID from the URL and injects it into the value of the hidden field.
A sample URL in this option looks like:
Where lnsg= is our query parameter for the visitor’s session GUID.
Option 2: Direct Injection
This option can be used if your form is not inside an iframe on the page. With that confirmed, we can modify your Liine SDK to inject the session GUID directly in to the hidden field on the form, but we need to be able to target the field via HTML attributes. To do so:
Your team sets the placeholder attribute of the hidden custom field to
liine_guid_ph.We modify your Liine SDK to target that attribute.
Option 3: Liine Runtime Object
On any page where the Liine SDK snippet is in place, a global Liine object is available at runtime. This object exposes the current session GUID. Your web team can access the session GUID and inject it into the hidden form field or insert it directly into the form payload at the __liine_session_guid key.
To get the session GUID:
Access
Liine.sessionGUID;
Step 3: Webhooking
Once your form payloads are structured correctly and the hidden field is added, reach out to your Liine team to request a 'form setting' URL. This is the URL for you to webhook those form submissions to.
Webhooking is a mechanic wherein most form builders will allow you to enter a URL(s) of your choosing to send form payloads to upon submission. This is how we set up Liine to be downstream of your form submissions, or more simply, where the form data is actually sent to Liine.
Step 4: Mapping and Verification
Once that webhook URL is in place on your form, please share the URL(s) – in production or staging/testing environments – where the form lives with the Liine team. With everything in place, the Liine team will complete mapping the form data into your Liine dashboard and any last touches/coordination needed. Once form submissions look as expected in your Liine dashboard, you're good to go!
Step 5: Ongoing Maintenance
If you're planning to make any changes to forms or data is not coming in as expected, please reach out to your Liine team.