Ensure that the Surface Tag has been added to the site before proceeding.

Use Our Template

Start with our multi-step form template to simplify implementation.

Form Builder

Prefer a no-code solution? Use our form builder instead.

​
Step 1: Add the SurfaceExternalForm script to your site

To ensure that the Surface Tag tracks the correct site, the siteId attribute must be added to the SurfaceExternalForm script.

​
Embed the script in the <head> or at the end of the <body> tag

The script must be added before the closing </body> tag and replace SITE_ID with the site ID.
<!-- Before the closing </body> tag -->
<script siteId="SITE_ID">
  const surfaceExternalForm = new SurfaceExternalForm();
  surfaceExternalForm.attachFormHandlers();
</script>

​
Step 2: Create an external form in Surface

​
Create a new form in Surface Labs

  1. Log in to the Surface Labs account.
  2. Navigate to the Forms section.
  3. Click “Create New Form”.
  4. Select “External Form Integration”.

​
Add required fields

When linking an external form, all fields that need to be tracked in Surface Forms must be added. The form builder provides several field types to match the form’s structure:

​
Available field types

  • Identity Info: Collects personal information like name, email, or phone number.
  • Short Input: For short text responses (single line).
  • Long Input: For longer text responses (multi-line).
  • Dropdown: For selection from predefined options.
  • Multiple Choice: For radio button or checkbox selections.
Once all fields have been added, they will be ready to map to the external form using the question IDs provided in the next steps.

​
Get integration details

After creating the form and adding all fields, the Component Question IDs for each form field must be obtained.
Question ID location in Surface Labs dashboard

​
Step 3: Create a multi-step HTML form

Either create a custom multi-step form or use the starter template.
  1. Clone the repository:
git clone -b demo https://github.com/trysurface/multi-step-progressive-form
  1. Open the project and review the index.html file.

​
Add the form ID to the <form> tag

<form id="multiStepForm" data-id="<Your_Form_ID>">
  <!-- Form steps here -->
</form>
Replace <Your_Form_ID> with the ID of the external form created in Surface Labs.

​
Add question IDs to form fields

Each field in the form requires a corresponding question ID from Surface Labs to be added to the data-id attribute: 
<div class="form-group">
  <label for="email">Business email</label>
  <input
    data-id="<Component_Question_ID>"
    type="email"
    id="email"
    name="email"
    placeholder="john@telnyx.com"
    required
  />
</div>
Replace <Component_Question_ID> with the question ID obtained while adding components to the external form.

​
Add the surface-next-button class to buttons

Add the surface-next-button class to all next buttons. 
<button type="button" class="surface-next-button">Next</button>

​
Add the surface-submit-button class to the submit button

Add the surface-submit-button class to the submit button. 
<button type="submit" class="surface-submit-button">Submit</button>

​
Troubleshooting

If issues are encountered:
  1. Form submissions not appearing:
    • Verify the form ID is correct.
    • Check that question IDs match those in Surface Labs.
    • Ensure the Surface Tag is properly installed.
    • Ensure the submit button has the surface-submit-button class.
  2. Partial responses not tracking:
    • Ensure that each ‘Next’ button has the surface-next-button class.
    • Check the network tab to confirm requests are being sent.
  3. Script not working:
    • Verify the script has the defer attribute if added to the <head> tag.
    • Check the browser console for errors.

​
Next Steps

Configure Workflows

Set up automated actions based on form submissions.

Lead Scoring

Configure lead scoring to prioritize high-value prospects.

Integrations

Connect Surface Labs to CRM, marketing tools, and more.

Analytics (Coming Soon)

Deep dive into form performance metrics.