Forms SDK best practices for Default

The Default Forms SDK lets your own code submit a form to Default and handle the workflow result. Use this guide when your page owns form submission or does not use a native <form> element. After you apply this pattern, your integration starts identity work early and handles every workflow result safely.

Use the automatic Pixel when your page has a standard HTML form and your code does not control submission.

Before you begin

Complete the pictured setup guide first. You need:

A form added in Forms, with mapped fields.
The public key and Pixel form UUID from the form’s Install tab.
An HTML ID for the form on your page.
A test page and synthetic visitor data.

Complete example

This standalone example denies analytics and marketing until there is a saved choice. It sets that choice before calling init(). Have your banner send its current choice and later changes through DefaultPixelSDK.setConsent() once the SDK is available. See Consent gating. When you also install the Pixel, use its complete generated loader and the saved-choice check before either downloaded script runs. The SDK applies choices queued on the Pixel loader, so you do not need to wait for the Pixel before loading it. The script address in this example is a placeholder; use each script address in your copied snippet.

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

<body>
	<form id="request-demo" data-default-ignore>
		<label>
			Work email
			<input id="work-email" name="email" type="email" required />
		</label>
		<label>
			First name
			<input id="first-name" name="first_name" required />
		</label>
		<button type="submit">Request a demo</button>
		<p id="form-status" role="status"></p>
	</form>

	<script>
		window.addEventListener('load', () => {
			function hasStoredDefaultChoice() {
				const match = document.cookie.match(/(?:^|;\s*)_dflt_consent=([^;]*)/)
				if (!match) return false
				try {
					const stored = JSON.parse(decodeURIComponent(match[1]))
					return stored.v === 1 && typeof stored.analytics === 'boolean' && typeof stored.marketing === 'boolean'
				} catch {
					return false
				}
			}
			if (!hasStoredDefaultChoice()) {
				DefaultPixelSDK.setConsent({ analytics: false, marketing: false })
			}
			DefaultPixelSDK.init({
				publicKey: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
				schedulerOrigins: ['https://book.default.com'],
			})

			const form = document.getElementById('request-demo')
			const email = document.getElementById('work-email')
			const firstName = document.getElementById('first-name')
			const status = document.getElementById('form-status')
			const submitButton = form.querySelector('button[type="submit"]')
			let submissionPending = false

			email.addEventListener('blur', () => {
				if (!email.validity.valid) return

				DefaultPixelSDK.recordFormInteraction({
					pixelFormId: '11111111-1111-4111-8111-111111111111',
					formId: form.id,
					fieldName: email.name,
					fieldValue: email.value,
				})
			})

			form.addEventListener('submit', async (event) => {
				event.preventDefault()
				if (submissionPending) return

				submissionPending = true
				submitButton.disabled = true
				status.textContent = 'Sending…'

				try {
					const result = await DefaultPixelSDK.submitForm({
						pixelFormId: '11111111-1111-4111-8111-111111111111',
						formId: form.id,
						responses: {
							email: email.value,
							first_name: firstName.value,
						},
					})

					if (!result.success) {
						status.textContent = 'We could not send your request. Please try again.'
						return
					}

					if (!result.scheduler && !result.redirect) {
						status.textContent = 'Thank you. We will be in touch.'
					}
				} finally {
					submissionPending = false
					submitButton.disabled = false
				}
			})
		})
	</script>
</body>

The default submitForm() behavior shows a returned scheduler in a modal. A redirect handoff always navigates the browser. The success message above appears only when neither handoff exists.

Use the correct form identifiers

The 2 identifiers serve different purposes.

Value	Meaning	Where to use it
`formId`	The HTML `id` on your page, such as `request-demo`	`recordFormInteraction({ formId })` and `submitForm({ formId })`
`pixelFormId`	The UUID Default assigns when you add the form	`recordFormInteraction({ pixelFormId })` and `submitForm({ pixelFormId })`

recordFormInteraction() and submitForm() must share at least one identifier, pixelFormId or formId. The warmup is filed under each one the blur carried, and the submission looks it up by each one it carries. Two calls with no identifier in common cannot reuse the early result.

The form must exist in Default before submitForm() can match it. Add it with Catalog forms under Forms → Create new, or, when the form carries data-default-ignore or isn’t a <form> element, create it under Forms and set its Form ID(s) to the same id. Field names in Default should match the input name attributes. See Create a form in Default.

Initialize before the visitor uses the form

Initialize the SDK before the visitor uses the form. The complete example calls init() after setting initial consent. If you use window.__defaultPixel__.key, the SDK initializes when it loads; set initial consent through the generated Pixel loader; the SDK applies it when it loads. Do not create the script or call init() inside the submit handler. Late initialization misses the email blur, delays identity work, and can delay the scheduler handoff. If your app supplies the key at runtime, call DefaultPixelSDK.init() once when your page or shared layout starts. Reuse the initialized SDK across form components. init() returns no promise.

Start pre-enrichment after a valid email

Call recordFormInteraction() when the visitor leaves a valid email field. This starts identity and company lookup before submission. Treat this call as best-effort. Do not block the form if it fails. Avoid sending the same unchanged email repeatedly. The SDK waits for this early lookup when a matching submission begins. It uses the saved result once. It ignores a saved result when its email differs from the submitted email.

Submit once and handle every result

Disable the submit button while the promise is pending. This prevents duplicate requests from quick clicks. submitForm() resolves with success: false for request failures. Check the result instead of depending on a thrown error.

Keep the default scheduler modal unless your page needs another display.
Use { target: "#meeting-section" } for an inline scheduler.
Use false only when your code will handle result.scheduler.url.
Expect redirect handoffs to navigate immediately. autoDisplayScheduler does not stop them.

Trust scheduler messages only from your scheduler

Set schedulerOrigins to the scheduler origins your page uses. The SDK drops messages from origins outside that list. Do not include broad or unrelated origins. Include each exact origin, including the scheme.

Exclude pages and forms from capture

Add this meta tag to disable form capture for a page:

<meta name="default:pixel" content="noform" />

Add data-default-ignore to a form or one of its parent elements to skip only that form:

<form id="internal-search" data-default-ignore>…</form>

For any form that your code submits with submitForm() while the Pixel also runs, put data-default-ignore on the form, its embed container, or a wrapper. Without it, the Pixel can also capture the same submission, and the workflow can run twice. This includes native HTML forms and the editor’s Embed this form sample. Ignored forms do not send automatic email interactions either. Keep the explicit recordFormInteraction() call from the complete example if you want early enrichment. The Pixel also skips paths containing /login, /signin, /account, /checkout, /oauth, and paths under /admin/.

Verify the result

Use the form editor’s Test tab with made-up data, then test the published website. The editor test does not exercise the website’s email blur or submission handler. Confirm these results:

Pre-enrichment starts after email blur.
The submission returns success: true and appears once in Recent Submissions. Success alone does not prove it was saved.
The correct Form Submission workflow runs after it is published.
The scheduler opens in the selected display mode.
Failure states leave the visitor with a clear next action.

Troubleshooting

Problem	What to check
Pre-enrichment starts only after submission	Initialize the SDK on page load. Call `recordFormInteraction()` after a valid email blur.
The early result is not reused	Pass a shared `pixelFormId` or `formId` to both `recordFormInteraction()` and `submitForm()`.
The form sends duplicate requests	Use `data-default-ignore` when the Pixel also runs. Disable the submit button while `submitForm()` is pending.
The scheduler does not appear	Check `result.scheduler`, `autoDisplayScheduler`, and the configured target element.
Scheduler events do not arrive	Add each exact scheduler origin, including `https://`, to `schedulerOrigins`.

Next steps

Understand the full integration

Learn how identity, form capture, workflows, and scheduler handoffs work together.

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

Forms SDK best practices for Default

Before you begin

Complete example

Use the correct form identifiers

Initialize before the visitor uses the form

Start pre-enrichment after a valid email

Submit once and handle every result

Trust scheduler messages only from your scheduler

Exclude pages and forms from capture

Verify the result

Troubleshooting

Next steps

Understand the full integration

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

​Before you begin

​Complete example

​Use the correct form identifiers

​Initialize before the visitor uses the form

​Start pre-enrichment after a valid email

​Submit once and handle every result

​Trust scheduler messages only from your scheduler

​Exclude pages and forms from capture

​Verify the result

​Troubleshooting

​Next steps

Understand the full integration

Use the API reference

Before you begin

Complete example

Use the correct form identifiers

Initialize before the visitor uses the form

Start pre-enrichment after a valid email

Submit once and handle every result

Trust scheduler messages only from your scheduler

Exclude pages and forms from capture

Verify the result

Troubleshooting

Next steps