How the Default Pixel and Forms SDK work

The Default Pixel and Forms SDK capture form submissions on your website and hand visitors to a scheduler. Use this guide to understand how Default processes a visitor from page load to scheduler handoff. You will also learn why late initialization delays identity lookup and can prevent the scheduler from appearing. For domain setup, adding forms, and field mapping, follow Set up the Pixel and Forms SDK. Use the API reference when you need an exact option, method, or event.

The Pixel and Forms SDK

The Pixel uses index.js; the Forms SDK uses sdk-core.js. When analytics is allowed, submissions from the SDK carry the visitor ID the Pixel stored, so they join that visitor’s page views. You can load either or both on the same page. Shared visitor identity does not prevent duplicate form submissions. When your code submits a form through the SDK, exclude that form from automatic Pixel capture with data-default-ignore. See Prevent duplicate submissions.

Script	Global	What it’s for
The Pixel (`index.js`)	`window.DefaultPixel`	Detects on its own which form was submitted, what a visitor typed, and when they viewed a page. You write no code beyond the install snippet.
The Forms SDK (`sdk-core.js`)	`window.DefaultPixelSDK`	A programmatic API you call yourself to report a submission and its values. Use it for custom-built forms (React, Vue, a multi-step flow), or for explicit control over what happens next.

Most sites only need the Pixel. Use the SDK in these cases:

Your form is not a plain HTML <form> element.
You want to control exactly how, or whether, the scheduler appears after submission.

See API reference for the full method and configuration list for each.

How it works, end to end

The script loads and initializes. It runs as soon as the page is ready, or immediately if the page already finished loading.
With analytics allowed, the Pixel establishes visitor identity and a 30-minute rolling session, and records pageviews. The standalone SDK does none of that. It uses the Pixel’s visitor ID when the Pixel has stored one, and otherwise an ID that lasts for the browser tab.
The automatic Pixel fetches the list of forms wired to a scheduling workflow. It does this at startup, before the visitor gets near the submit button.
Pre-enrichment starts while the visitor fills out a tracked form. The moment they finish typing their email and move to the next field, the script sends what they entered so far to Default. Default only starts the lookup when the form is approved, has Allow pre-enrichment on, and a published workflow attached to it enriches, and a primary waterfall is configured.
If Default recognizes the email, it identifies the company and person in the background. It also checks your CRM for a matching record, before the visitor clicks submit.
The visitor submits. The script, or your code if you use the SDK, sends the full responses to Default with the pre-enrichment and CRM match results that are ready by then.
Published workflows attached to an accepting form can run. Routing, enrichment, and scheduling happen in Default, exactly as configured in your workspace.
The workflow hands back the next action:
- Nothing. The page shows its own thank-you state.
- A redirect to a specific URL.
- A scheduler handoff. The script shows the booking calendar (see The scheduler experience).

Steps 3 to 5 go wrong when you install the script late. See Initialize on page load, not at submit below.

Install

The snippet

Copy your snippet

Select Settings in the sidebar, then Domains, open a website domain, then find Add the snippet to your site. The snippet comes with your workspace’s public key already filled in. Your workspace has 1 key, so the same snippet works on every domain you connect.Copy the complete generated loader. It includes load retries and a consent method that works before the downloaded scripts start. Use the snippet shown under Add the snippet to your site without changing its script addresses.

Add the SDK script if you use it

To load the programmatic SDK on the same page, load it the same way with sdk-core.js in place of index.js. Both scripts read the same window.__defaultPixel__.key. Use each script address in your copied snippet; the address below is an example.

<script async src="https://handshake.default.com/sdk-core.js"></script>

The SDK applies consent choices queued on the install loader, and it sets no tracking cookies, so it is safe to load at any point. For a standalone SDK, see the complete example.

The key value is a public key. It belongs in client-side code, so you do not have to hide or proxy it.

Where it goes

Put the snippet in the <head> of every page you want tracked.

Add it to your site-wide template or layout. You then do not have to add it page by page.
A tag manager also works. Use a custom HTML tag that fires on all pages.
Single-page apps need the snippet only once. The script detects client-side route changes on its own and re-evaluates each new “page” without a reload.

Initialize form handling before the visitor uses the form. Do not defer it until submission.Your cookie banner can disable tracking while forms remain available. Follow Connect your cookie banner.The next section explains exactly what that breaks.

Initialize on page load, not at submit

This is the most common integration mistake we see. It is worth understanding why it matters, not just that it does. Some things happen correctly only when the script runs from the moment the page loads:

1. Pre-enrichment and CRM matching lose their early start

The script starts to identify a visitor the moment they leave the email field, well before submit. It also starts to check your CRM then. This works only when the script’s interaction listeners were attached before the visitor typed their email. If the script, DefaultPixelSDK.init(), or the visitor’s <form> shows up later, nothing catches that moment. The submission still goes through. But Default must then do the identification and CRM lookup after submit, which adds real time between “submit” and “here’s your calendar.”

2. The scheduler-enabled forms list may not have loaded yet

Right after it starts, the script fetches the list of forms on the page wired to a scheduling workflow. It then knows in advance to intercept those forms’ native submit behavior and show the calendar instead. Interception stops the browser from navigating to the form’s plain action URL. If the script only starts at submit time, that fetch has possibly not finished. In the worst case, the browser follows the form’s default action. The visitor never reaches the calendar at all.

3. Identity resolution needs a moment to run

This applies to the Pixel. Its stable anonymous visitor id takes a moment to generate, so a submission that fires in the very first instant of the script’s life may fall back to a temporary id for that one event. The Forms SDK has no such delay: it reads the Pixel’s id, or its own per-tab id, immediately. All 3 point at the same fix:

<!-- In <head>, before the visitor uses the form -->
<!-- Paste the complete generated install snippet from Settings → Domains here. -->

<!-- Don't do this: script only appears once the visitor is already submitting -->
<form id="demo-form" onsubmit="loadPixelScriptThenSubmit()">
  ...
</form>

The visible symptom is exactly what it sounds like. Booking slots take a noticeably long time to appear after the visitor submits, or the calendar never appears at all. The fix is always the same. Load and initialize the script, or call DefaultPixelSDK.init(), on page load. Do not do this inside a submit handler. Do not put it behind a condition that delays it past the visitor’s first interaction with the form. The same rule applies when you call recordFormInteraction() yourself to mirror the email-blur warmup (see Form binding below). Call it as soon as the visitor supplies their email, not at submit time.

Form binding

Automatic detection (the Pixel)

Once running, the Pixel recognizes forms on its own. That includes forms added to the page after load, for example inside a modal or after a client-side route change:

Plain HTML forms: any <form> element that does not match one of the vendor patterns below. The script listens for its submit event and for focus, blur, and change activity on its fields.
HubSpot forms: the script recognizes a form id that starts with hsForm_, a hs-form class, an hs_context hidden field, or an action that points at HubSpot’s form domains. It also recognizes HubSpot’s newer embed through that embed’s own ready and submission events.
Marketo forms: the script detects these through Marketo’s own form-ready API.
Paperform embeds: the script detects these through Paperform’s own submission messages.

The script also picks up forms in a same-origin iframe, one it can read into. It cannot read into a cross-origin iframe, for example a landing-page builder hosted on someone else’s domain. If you control that cross-origin iframe’s content, add the install snippet inside it directly.

Manual submission (the SDK)

For a form the Pixel cannot detect cleanly, call the SDK directly instead. A fully custom React or Vue form is a typical case:

const result = await DefaultPixelSDK.submitForm({
  pixelFormId: "your_pixel_form_id", // the id Default assigned when you added the form
  responses: {
    email: "jordan@acme.com",
    first_name: "Jordan",
    company_domain: "acme.com",
  },
});

See submitForm in the reference for the full option list and return shape. Each form in Default also ships a working code sample for this exact call. Open Forms, select a form, select Edit Form, then open its Install tab, section Use the SDK. The sample comes pre-filled with your real public key, form id, and field names. Split it apart rather than paste it as one block. Keep the init() call and script tag on page load, exactly as shown, per Initialize on page load, not at submit above. Move the submitForm() call to wherever your own code actually collects a submission. As pasted, the sample calls both immediately. That confirms the connection works, but it is not a real integration. The neighboring Test tab fires real test submissions and pre-enrichment against your fields. You do not have to leave the editor. If your custom form’s fields are outside a native <form> or carry data-default-ignore, automatic email interactions do not run. Call recordFormInteraction() yourself as soon as the visitor leaves the email field, so pre-enrichment still gets its early start:

document.getElementById("email-field").addEventListener("blur", (e) => {
  DefaultPixelSDK.recordFormInteraction({
    pixelFormId: "11111111-1111-4111-8111-111111111111", // Default's form UUID
    formId: "request-demo", // optional: the HTML form id
    fieldName: "email",
    fieldValue: e.target.value,
  });
});

Pass the same pixelFormId to submitForm(). The warmup is filed under every identifier the blur carried, so the submit finds it by pixelFormId or by a shared HTML formId. See recordFormInteraction for the full signature.

Excluding a page or a form from capture

Turn off capture for an entire page with a meta tag in that page’s <head>:
<meta name="default:pixel" content="noform">
The script skips sensitive paths automatically: /login, /signin, /account, /checkout, /oauth, and any path under /admin/.
To exclude one form without opting out the whole page, add a data-default-ignore attribute to that form or to any element that wraps it:
<form id="internal-tool-form" data-default-ignore> ... </form>
The same attribute works on HubSpot, Marketo, and Paperform embeds. Put it on the element the embed renders into, or on a wrapper around it. Do this whenever your own code submits that form with submitForm(). Otherwise the Pixel also captures the vendor’s submission, and the workflow runs twice.
<div data-default-ignore> <div class="hs-form-frame" data-region="na1" data-form-id="..." data-portal-id="..."></div> </div>

The scheduler experience

The Pixel and the SDK both show the booking calendar the same way. It is a full-screen overlay on top of your page. The calendar renders its own dimmed backdrop and card. It reads as a modal without a second frame around it. Before the calendar itself is ready, a branded loading indicator appears first. It uses your workspace’s scheduler colors and logo, if you set them. A short rotating message tells the visitor that something is happening. Once the calendar is ready, it replaces the indicator in a single swap, with no blank flash in between. If the visitor’s pre-enrichment and CRM matching already ran early (see above), this handoff is fast. If the script had to do that work after submit, the visitor sits in this loading state longer. The autoDisplayScheduler option controls the display mode. Set it on DefaultPixelSDK.init() or in the window.__defaultPixel__ block, which both scripts read. You can also override it per call to DefaultPixelSDK.submitForm():

Modal (default): the full-screen overlay described above. Nothing to configure.
Inline: the calendar mounts into a container element you specify, so it feels like part of your page. Add loader: true to also show the branded loading indicator in that container while the calendar loads.
await DefaultPixelSDK.submitForm({ pixelFormId, responses, autoDisplayScheduler: { target: "#meeting-section", loader: true }, });

Off: the script displays nothing, and you read the URL off the result yourself. This mode only exists for submitForm().

const result = await DefaultPixelSDK.submitForm({ pixelFormId, responses, autoDisplayScheduler: false });
if (result.scheduler) {
  window.location.href = result.scheduler.url;
}

A plain HTML form the Pixel auto-detects can render inline too, with no SDK call involved. Set window.__defaultPixel__.autoDisplayScheduler = { target: "#meeting-section" } in your install snippet, and the Pixel mounts the calendar there on a scheduler handoff. An auto-detected form cannot turn display off. The true/false shape of autoDisplayScheduler only affects submitForm(). On a scheduler handoff, an auto-detected form always shows the calendar somewhere, full-screen or in your target container. There is no calling code for the Pixel to hand a suppressed URL back to. A calendar you displayed through submitForm() closes itself in these cases:

The visitor books or cancels.
The booking session times out.
A workflow is configured to redirect afterward.

On an auto-detected form, the calendar closes when the visitor closes it, on Escape, or if it fails to load. For the full event list you can subscribe to (booked, canceled, closed, and so on), see Scheduler events in the reference. Subscribing works the same way from either script, with DefaultPixel.on(...) or DefaultPixelSDK.on(...). You do not need the SDK on the page just to listen for scheduler events.

Troubleshooting

Symptom	Likely cause	Fix
Booking slots take a long time to appear after submit, or the calendar feels laggy	The script initialized late, for example inside a submit handler. Pre-enrichment and CRM matching then run after submit instead of early.	Initialize on page load, in the `<head>`. See Initialize on page load, not at submit
The browser navigates to the form’s plain action URL instead of showing the calendar	Same root cause. The script had not yet learned this form was wired to a scheduling workflow.	Same fix: initialize on page load
A form does not show up as detected, or submissions do not come through	Check, in order: a `<meta name="default:pixel" content="noform">` tag, a `data-default-ignore` attribute on the form or an ancestor, a sensitive path like `/login` or `/checkout`, a cross-origin iframe, or a missing snippet on that page	Remove an unintended meta tag or attribute, and confirm the snippet is on the page you test. If the form lives in an iframe, add the snippet inside that iframe’s own page.
A HubSpot, Marketo, or Paperform form is not detected even though it is the right vendor	The embed does not match that vendor’s standard markup or script, for example a heavily customized or self-hosted embed	Confirm the embed uses the vendor’s standard script and markup. Or submit explicitly with `DefaultPixelSDK.submitForm()`.
A Pardot form’s submissions never arrive	Automatic detection does not capture Pardot forms today	Submit explicitly with `DefaultPixelSDK.submitForm()`. It works regardless of the form’s vendor.
With the Pixel, the very first submission on a page looks like a brand-new anonymous visitor, even for a returning one	The Pixel’s identity resolution had not finished yet, most likely because the script only started at submit time	Initialize on page load. Identity then has time to resolve before any real interaction. The Forms SDK alone never recognizes a returning visitor, because it stores no visitor ID of its own.
The calendar never appears, or the console shows a warning about an invalid scheduler URL	The URL from the workflow failed the script’s safety check. The script only ever renders your Default domain, over HTTPS.	Check the workflow’s Display Scheduler step and its destination.
`submitForm()` resolves with `success: false`	A 404 status means the explicit form ID is not active in the workspace tied to your public key. Other non-2xx statuses are network or server errors.	Check `result.status` and `result.error`. Confirm the active form and workspace match, then retry or fall back to your own confirmation flow.
`submitForm({ pixelFormId })` submits against the wrong form (or none) on a page with more than one `<form>`	With only a `pixelFormId`, the SDK guesses which DOM form you mean: the currently focused field’s form, or a form tagged with a matching `data-pixel-form-id`	Also pass `formId`, the form’s HTML id. Or add a `data-pixel-form-id` attribute that matches the id you submit against.

Next steps

Set up the Pixel and Forms SDK

Connect a domain, add a form, install the SDK, and verify a workflow.

Build a reliable Forms SDK flow

Apply the recommended initialization, submission, and scheduler pattern.

Use the API reference

Find every configuration option, method, return value, and scheduler event.

Overview

Get started

Switching to Default

Guides

Tables

Enrichment and data

Routing

Scheduling

Workflows

Forms

Pixel and Forms SDK

MCP

Chrome extension

Settings

API

How the Default Pixel and Forms SDK work

The Pixel and Forms SDK

How it works, end to end

Install

The snippet

Where it goes

Initialize on page load, not at submit

1. Pre-enrichment and CRM matching lose their early start

2. The scheduler-enabled forms list may not have loaded yet

3. Identity resolution needs a moment to run

Form binding

Automatic detection (the Pixel)

Manual submission (the SDK)

Excluding a page or a form from capture

The scheduler experience

Troubleshooting

Next steps

Set up the Pixel and Forms SDK

Build a reliable Forms SDK flow

Use the API reference

Overview

Get started

Switching to Default

Guides

Tables

Enrichment and data

Routing

Scheduling

Workflows

Forms

Pixel and Forms SDK

MCP

Chrome extension

Settings

API

​The Pixel and Forms SDK

​How it works, end to end

​Install

​The snippet

​Where it goes

​Initialize on page load, not at submit

​1. Pre-enrichment and CRM matching lose their early start

​2. The scheduler-enabled forms list may not have loaded yet

​3. Identity resolution needs a moment to run

​Form binding

​Automatic detection (the Pixel)

​Manual submission (the SDK)

​Excluding a page or a form from capture

​The scheduler experience

​Troubleshooting

​Next steps

Set up the Pixel and Forms SDK

Build a reliable Forms SDK flow

Use the API reference

The Pixel and Forms SDK

How it works, end to end

Install

The snippet

Where it goes

Initialize on page load, not at submit

1. Pre-enrichment and CRM matching lose their early start

2. The scheduler-enabled forms list may not have loaded yet

3. Identity resolution needs a moment to run

Form binding

Automatic detection (the Pixel)

Manual submission (the SDK)

Excluding a page or a form from capture

The scheduler experience

Troubleshooting

Next steps