Custom forms integration

You can connect forms to your Customer.io workspace to automatically add people and trigger campaigns when they submit your form. Connecting forms to your workspace makes it easy to capture and respond to leads.

There are two ways to connect forms to your workspace:

Use the Custom forms JavaScript snippet with a compatible form provider.

You provide the URL of a page containing a form supported by our JavaScript snippet. We scan the page for your form and the fields on that form, letting you map form fields to attributes on the people who respond to your form. Forms captured this way also capture query parameters in the URL of the page containing the form. You can use URL parameters that we capture for segmentation, but we do not apply them to people who fill out your form as attributes.

 The Custom forms JavaScript snippet is different from our basic JavaScript snippet

You can find the JavaScript snippet for forms on the Forms page in the Settings tab; you must install this snippet to send form submission data to Customer.io.
Use the Forms API (generally for backend integrations).

You pass a form_id, along with the data you want to capture from that form. If the form, or the person you reference in the data of your request, do not exist, we create them!

This is typically for backend integrations. We do not currently support form submissions from the <action> tag; client-side form submissions require JavaScript. And, while you can write your own client-side JavaScript integration with the Forms API, our Custom forms JavaScript snippet is ready-made for that purpose.

These processes are not for Facebook Lead Ad forms. See our Facebook Lead Ads page for more information about that integration.

Use the Custom forms JavaScript snippet

To capture form submissions using the Custom forms JavaScript snippet, you need to:

  1. Scan your form to Customer.io on the Data & Integrations > Forms page. For us to scan your form, it must:
    • Use a <form> tag. We cannot scan <div>-based forms.
    • Not be inside an <iframe>.
    • Have fields with name attributes; name is how we identify non-textarea fields and map them to attributes.
    • Have a field that maps directly to one, and only one identifier—id or email as determined by your workspace settings.
  2. Install the Custom forms JavaScript snippet on the page(s) containing your form.

You can do these things in any order, but you cannot capture form information until you’ve done both.

Scan a form

To add a form, provide the URL of the page containing your form. Customer.io can scan most forms that use the <form> tag, as long as your form is not inside an <iframe> and your form fields have name attributes. If your form contains <textarea> fields that do not have a name (as with Squarespace), we’ll number them (e.g. textarea_1).

 If your form is on multiple pages, you only need to add your form once.

If you have instances of the same form on multiple pages, we’ll treat them as the same form (so long as the Custom forms JavaScript snippet is installed on all pages containing the form).
  1. Go to Data & Integrations > Forms.
  2. Select Custom and click Connect form.
  3. Enter the URL of your form and click Scan for Forms.
  4. Select the form(s) you want to connect to your workspace and click Choose Form. If your page contains multiple forms, you can select each form and set a Name. The Name is how you’ll select forms in the UI.
  5. Map Form Fields to Attributes and click Set Up Form. By default, we map the names of each field directly to an attribute. Click to prevent Customer.io from capturing a field. Take care when mapping fields; attribute names and values are case sensitive. If you segment or trigger campaigns based on attribute names and values, you want to make sure that you assign attributes and values correctly.
    map form fields to attributes
    map form fields to attributes
  6. If you haven’t already, Install the Custom forms JavaScript snippet. Go to the Settings tab to find the snippet.

Install the Custom forms JavaScript snippet

The Custom forms JavaScript snippet is not the same as our basic JavaScript snippet. You must install the Connected forms JavaScript snippet to send data from scanned forms back to Customer.io.

Before you can find the Custom forms JavaScript snippet, you must have scanned at least one form.

To find and install this snippet:

  1. Go to Data & Integrations > Forms and click Settings. The Settings tab only appears after you scan your first form. If you haven’t already done so, scan a form.
  2. Click JS Snippet.
    click JS snippet on the forms settings page
    click JS snippet on the forms settings page
  3. Copy and paste the snippet. Where you paste the snippet may vary based on your form provider.
    • Custom HTML or Netlify Forms: paste the script on the page containing your form. The script can go anywhere in the <head> or <body> tags.
    • Other form providers: See the supported providers below.

 You can install both Customer.io JavaScript snippets

We have two JavaScript snippets: the basic JavaScript snippet and the Custom forms snippet. The basic snippet identifies and updates people who browse your website, and the custom forms snippet identifies and updates people who submit your form.

Compatible form providers

To use our form-scanning service, form fields must have a name attribute and you need to install the Custom forms JavaScript snippet. This snippet is different from our basic JavaScript snippet and has been tested with the following services and forms, though it may be compatible with additional services:

We can also support virtually any form provider when you integrate directly with the /forms API. In general, we suggest using the API for backend integrations; we do not support submissions directly from the HTML action attribute, and, while you can write your own JavaScript integration with this API, our Custom forms JavaScript snippet is made specifically for this purpose.

Formstack

In Formstack, you add JavaScript to a theme. You cannot add a script to the default theme. You either need to create a new theme or copy an existing one so that you can edit it.

To add the Custom forms JavaScript to your Formstack theme:

  1. Go to the form containing your theme.
  2. Click Style and then click Advanced Code Editor.
  3. Paste the Custom forms JavaScript snippet into the Header HTML or Footer HTML; it doesn’t matter which.
  4. Click Save Changes.
add Custom forms JavaScript in formstack
add Custom forms JavaScript in formstack
Map Formstack fields to attributes

Formstack does not assign a friendly name attribute to fields. Instead, it assigns a numeric identifier value to the name attribute in each field in the format field113891598, which can make it challenging to map form fields to attributes. You need to know which name attribute corresponds to the field label, so that you can accurately map fields to attributes in Customer.io.

When you scan a form, fields generally appear in order from top-to-bottom, left-to-right, which may help you understand the order of fields when you map them to attributes. Otherwise, you can find the names of your fields by examining the HTML on your form page, or in Formstack by going to Forms, selecting your form, and then clicking the field you want to find the identifier for. The URL updates with each field you select; the final segment in the URL path represents the field identifier (in the format field<identifer>).

 Send a test event to check Formstack field mappings

Because Formstack fields don’t have friendly names, we strongly recommend that you send a test form_submit event to make sure that your fields map to the correct attributes. After you map your form, click Create Campaign for your Formstack form, and then click Test form event to send a test event representing a test user in your workspace. Click View submissions to see the incoming event and make sure that your form is mapped correctly.

Instapage

You can install the JavaScript snippet in the head, body, or footer of your Instapage form page. If you use a custom domain (as opposed to the default, pagedemo.co URL), it may take a while before you can begin transmitting data to Customer.io due to DNS propagation issues.

Netlify

Netlify forms are basically custom HTML forms that include a data-netlify="true" parameter in the <form> element.

Include the JavaScript Form Snippet on the page containing your form. It can go anywhere in the <head> or <body> tags. Form submissions will appear both in Netlify and as people in your Customer.io workspace.

Squarespace

You can add the Custom forms JavaScript snippet to Squarespace pages using the code injection feature. You can inject code at the page or site levels depending on how many pages contain your form.

  1. Click Settings > Advanced for the page or site you want to add code to.
  2. Paste the Custom forms JavaScript snippet in the header or body sections.
  3. Click Save.

 We automatically assign a name to Squarespace text area elements

We normally identify form fields by their name attributes. Squarespace does not let you assign a name to <textarea> elements, so we assign them names in the format textarea_1, with ascending numbers for each text area element in your form.

Unbounce

You can add the JavaScript snippet at the domain level or page level, but you should not add it in both places, or you’ll receive duplicate submissions for each form.

  • Add to the domain under Settings > Script Manager.
  • Add at the page level, click Javascripts at the bottom of the page and insert the Custom forms JavaScript snippet.

The JavaScript snippet does not work with forms in Unbounce popups or sticky bars.

Webflow

You must have a paid Webflow plan to add the Custom forms JavaScript snippet to Webflow forms pages. In Webflow:

  1. Go to Pages.
  2. Click for the page you want to install the Custom forms JavaScript snippet on.
  3. Scroll down to Custom Code and paste the Custom forms JavaScript snippet in either the Inside <head> tag or Before </body> tag. It doesn’t matter which.
  4. Click Save.
add Custom forms JavaScript in Webflow
add Custom forms JavaScript in Webflow

Form fields and URL parameters captured by the JavaScript snippet

The Custom forms JavaScript snippet captures both form fields and URL parameters on the page containing your form, but the two work differently: form fields are converted to attributesA key-value pair containing that you associate with a person. Use attributes to target people and personalize messages. on a person who submits a form; URL parameters are not.

Form Fields: When you set up a form in Customer.io, you scan a URL for forms. Customer.io identifies fields in your form by name attributes. After you scan a form, you determine which fields we capture, and map each field to an attribute for people who submit the form.

Customer.io also reserves three fields: form_id, form_name, and form_type; if fields on your form (or in your API payload) include these fields, we’ll ignore them.

  • form_id: Assigned by customer.io when you scan the form or through the API in the path.
  • form_name: Assigned when you map your form in Customer.io.
  • form_type: One of facebook or custom, representing the origin of the form.
  • form_url: The URL of the page that a user submitted your form from.
  • form_url_params: An array of URL parameters present when a user submitted your form.

URL Parameters: When someone submits a form, we capture URL parameters on the form page, so that you can segment people and filter campaigns based on these values. But, because URL parameters are not mapped to attributes when you connect your form to Customer.io, we cannot apply URL parameters to people as attributes.

URL parameters captured in this way appear in the form_url_parameters array, to help you understand which fields come from your form and which come from the page URL; items in this array are not applied to to a person as attributes. If a form field and URL parameter have the same name, the form field will win and we’ll ignore the URL parameter.

 Use an attribute change to apply URL parameters to people

By default, we only capture URL parameters for segmentation purposes. However, you can use an attribute change event in a form-triggered campaign to convert URL parameters to attributes for people who submit your forms.

Capturing the same form on multiple pages

If you have a form with the same fields on multiple pages, you only need to scan one URL; we capture submissions from all pages under the same form in Customer.io.

When you scan a form, we identify the form based on the fields contained in the form. Each field on the form is identified by its name, or, for textarea elements without names, we assign them a name in the format textarea_1.

When you integrate directly with our API, a unique form is determined entirely by the form_id. If you submit a form with the same fields on different pages, you can submit them with the same form_id to treat them as the same form, or set different form_id values to differentiate between your forms.

Form scanning errors

When scanning forms, you may run into some errors. In most cases, an error means that you’re trying to scan a form we don’t support, or you’re trying to scan a form that you’ve already scanned on another page.

No forms found under this address

In general, this means that the URL either does not contain a form, or contains a form we don’t support. This error appears when:

  • The URL contains forms we don’t support yet: Typeform, Jotform, HubSpot forms, etc. You’ll find a list of the form providers we currently support here.
  • The URL contains JavaScript-rendered forms. We do not yet support pure JavaScript forms.
  • The page contains <div>-based forms. Forms must use the <form> tag.
Form with same form fields already exists

You’ve scanned this form on another page, and you do not need to scan it again. We identify forms based on the fields they contain; if a form with identical, non-hidden fields exists on multiple pages, we’ll recognize it on any page you submit it from.

If you want to differentiate between form submissions across pages, consider adding a hidden field to the form that represents the page it’s submitted on.

Use the Forms API

If you don’t want to use our JavaScript snippet, you can write your own backend integration with the Customer.io /forms API. Even if you use our JavaScript snippet, you may want to maintain a backend API integration in case your audience blocks or disables JavaScript.

 You cannot submit forms to Customer.io using the HTML action attribute

Client-side form submissions require JavaScript. In general, we recommend using the /forms API to maintain a backend integration, and our Custom forms JavaScript snippet for client-side integrations.

To connect your form to Customer.io, just send a send a POST to https://track.customer.io/api/v1/forms/{form_id}/submit when someone submits your form. The form_id is an arbitrary string value representing your form. If we haven’t seen the form ID before, we create a new form connection (found on the Data & Integrations > Forms page). Requests with the same form ID are treated as submissions from the same form.

The payload of a request is a data object that must contain either id or email—or a field that you map to one of these —to identify the form respondent. If the person who submitted the form does not already exist, we create them.

Additional keys in the data object represent form fields and values from the form that a person submitted. By default, we map form fields in your request directly to attributes, e.g. if you have a form field called first_name, we map that field to the first_name attribute.

{
    "data": {
        // each key represents a form field
        // form fields map directly to attribute names unless you re-map them
        "first_name": "Cool Person",
        "email": "cool.person@example.com",
    } 
}

After you submit your first /forms request, you can re-map form fields to attributes on the Data & Integrations > Forms page. If you turn off a form field on the Forms page, you can still include it in your request, but it is ignored: is not converted to an attribute and applied to the person who filled out your form.

map form fields to attributes
map form fields to attributes

Mapping identifiers and initial form submission errors

If an identifier in your form does not map directly to an is called something like email_address rather than email in your initial request, you’ll receive a 400, but we’ll still add your form on the Data & Integrations > Forms page. You can then re-map your email_address field to email, and your form will begin working normally.

The forms page with a form added from the API
The forms page with a form added from the API

Edit a form

You can edit your form to add fields, re-map fields to attributes, or turn off fields you no longer want to capture. Your changes only reflect new respondents. Changing form fields doesn’t change attributes on people who already filled out your form.

If you move a form to a new page, you do not need to edit or re-scan your form. You simply need to make sure that the page you move the form to has the Custom forms JavaScript snippet.

  1. Go to Data & Integrations > Integrations and Select Forms.
    the forms page
    the forms page
  2. Select the form you want to edit and click Edit.
  3. Add, remove or re-map form fields.
    • Enable/disable fields: Check and un-check fields to enable and disable them.
    • Add fields: If your form uses the Custom forms JavaScript snippet, click Re-scan to update the fields on your form. If your form integrates directly with our API, click Add Field.
    • Edit field names: Change the names of attributes you want to map form fields to. If integrated with the /forms API, you can also change the name of the form field that you want to map.
  4. Click Save.

Disconnect a form

Disconnecting a form prevents Customer.io from collecting form submissions and identifying people who fill out your form. You can reconnect the form later, if you want to stop collecting submissions temporarily.

  1. Go to Data & Integrations > Forms.
  2. Click and then click Disconnect.
  3. Confirm that you want to disconnect the form.

Disconnected forms still appear in the forms list. You can find all your disconnected forms by selecting the Disconnected status.

Forms with the disconnected status
Forms with the disconnected status

Trigger a campaign from a form

Form submission events can trigger campaigns, making it easy to start a conversation with people and foster conversions immediately when they fill out your form.

You can start a form-triggered campaign by going to Data & Integrations > Forms and clicking Create campaign for the form that you want to trigger your campaign. This automatically populates a campaign trigger with your form name.

Or you can create a form-triggered campaign from the Campaigns menu:

  1. Go to Campaigns and click Create Campaign.
  2. Click They fill out a form and select the name of your form that you want to trigger your campaign.
  3. Continue creating your campaign. Each form submission triggers a campaign.
trigger a campaign from a form
trigger a campaign from a form

 Use hidden fields to filter campaigns based on form submissions from different pages

If your form appears on different pages, and you want to differentiate campaigns based on the page a person is on when they submit your form, you can click Add event data filter and filter for a hidden field that differentiates between your forms on different pages.

Form data in liquid

Remember that form submissions captured by the JavaScript snippet include both form fields and URL parameters from the page. You can access these variables in Liquid using different scopes.

Form Fields come in as event properties and are mapped to customer attributes. You can reference form fields either way, but remember that the event property represents the field name from the form, and the customer scope represents the mapped attribute name, and the two can be different if you re-mapped form fields to attributes when you set up your form.

For example, if you mapped a form field called msisdn to phone, then you could access the event property as {{event.msisdn}} or the customer attribute at {{customer.phone}}—both represent the same value!

URL Parameters are only available as event properties. For example, if you want to reference a URL parameter from the page that your form page called referred-by, you would use {{event.referred-by}}.

Form submission events in the Activity Log

Each form submission captured by the Custom forms JavaScript snippet or the API is recorded as a form_submit event. You can see these events in the Activity Log. Click an event to see the form_id and values that a person submitted.

Copied to clipboard!