Pixel and Forms SDK: API reference

Use this reference to find every option, method, return value, and scheduler event for the Default Pixel (index.js) and Forms SDK (sdk.js). Read Understand the Pixel and Forms SDK first to learn how the two scripts work together. Everything on this page comes from the script’s own source. We call out anything we could not confirm.

Entry points

	The Pixel	The Forms SDK
File	`index.js`	`sdk.js`
CDN URL	`https://pixel.default.com/index.js`	`https://pixel.default.com/sdk.js`
Global	`window.DefaultPixel`	`window.DefaultPixelSDK`
Programmatic API	`on()`, `scheduler.*`, and `submitForm()`, shared with the Forms SDK. It has no `init()` and no `recordFormInteraction()`.	The full set: `init`, `on`, `submitForm`, `recordFormInteraction`, `scheduler.*`.
Auto-initializes from	`window.__defaultPixel__.key`, `.schedulerOrigins`, and `.autoDisplayScheduler`	`window.__defaultPixel__` (all fields)

Both scripts read scheduler configuration from the same block and post to one shared scheduler event bus. on(), scheduler.*, and submitForm() therefore behave the same from either script. See Methods below for exactly which methods live on which global.

<script>
  window.__defaultPixel__ = {
    key: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    // `endpoint` is read by the SDK (sdk.js) only; the Pixel (index.js) always
    // uses Default's standard endpoint and has no way to override it here.
    // schedulerOrigins and autoDisplayScheduler are read by both scripts.
    // endpoint: "https://api.default.com",
    // schedulerOrigins: ["https://book.default.com"],
    // autoDisplayScheduler: true,
  };
</script>

Configuration

Shared configuration options

Set these options as window.__defaultPixel__, or pass them to DefaultPixelSDK.init(options) with the same shape. The init() path is useful when the key is only known at runtime. The SDK reads window.__defaultPixel__ automatically on load. A later init() call updates the configuration in place, but it does not re-run identity or session warmup. The Pixel (index.js) has no init() to call, but it reads key, schedulerOrigins, and autoDisplayScheduler directly off the same window.__defaultPixel__ block. Only endpoint is SDK-only.

Option	Type	Required	Default	Notes
`publicKey` (`key` in the global config block)	`string`	Yes	none	Your domain’s pixel public key. Without it, `init()` logs a warning, does nothing, and sends no requests.
`endpoint`	`string`	No	Default’s API endpoint	Override this only if Default tells you to point at a proxy. This option is SDK-only, and the Pixel cannot override its endpoint.
`schedulerOrigins`	`string[]`	No	The endpoint’s own origin, plus the matching scheduler origin if the endpoint’s hostname starts with `api.`	The origins that can post scheduler events, such as booked and closed, into the page. Both scripts read this option and silently drop events from any other origin.
`autoDisplayScheduler`	`boolean \| { target: string \| HTMLElement; loader?: boolean }`	No	`true`	Default behavior when `submitForm()` resolves to a scheduler URL. `true` shows the full-screen modal, and `false` shows nothing, so you read the URL yourself. `{ target, loader? }` mounts the calendar inline at a CSS selector or element, and `loader: true` also shows the branded loading indicator inside that container until the calendar loads. You can override this per call to `submitForm()`. For automatically detected forms, see the note below this table.

DefaultPixelSDK.init({
  publicKey: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  autoDisplayScheduler: { target: "#meeting-section" },
});

The Pixel (index.js) has no equivalent init() call. It always uses Default’s standard endpoint. It does read schedulerOrigins and autoDisplayScheduler off window.__defaultPixel__. See the table above. Automatically detected forms, which involve no submitForm() call, read only the { target, loader } shape of autoDisplayScheduler. The true and false values do not apply there, because the calendar always displays somewhere on a handoff. When target is set for an automatically detected form, the loading indicator defaults to shown. Set loader: false there to hide it. This default is the opposite of submitForm()’s. See The scheduler experience in the guide for what this means in practice.

Methods

on, submitForm, and scheduler.* are on both window.DefaultPixel and window.DefaultPixelSDK. init and recordFormInteraction are on window.DefaultPixelSDK only.

init

DefaultPixelSDK.init(options). This method exists only on window.DefaultPixelSDK, and the Pixel (index.js) has no equivalent call. Every call configures the SDK, and the first call also starts it. The start warms identity and session, and attaches the email-blur listener that powers pre-enrichment. The start also checks for a pending scheduler handoff left over from a same-page redirect. The method returns nothing. See Shared configuration options above for options. The SDK also calls this automatically on script load if window.__defaultPixel__.key is present. Most integrations never call it directly.

on

DefaultPixelSDK.on(eventType, handler). Subscribes to a raw scheduler event. Returns an unsubscribe function.

const off = DefaultPixelSDK.on("meeting_booked", (payload) => {
  console.log("booked", payload);
});
// later: off();

eventType is one of the five values in Scheduler events below. Most integrations use the typed helpers under scheduler.* instead. The helpers are equivalent, but they save you from typing the event name as a string.

submitForm

DefaultPixelSDK.submitForm(options). You can also call it as DefaultPixel.submitForm(options) on the Pixel bundle, but most integrations only need it via the SDK (see Entry points). It submits a set of field values directly to a known Pixel form, without going through form detection. It returns a promise, never throws on a failed request, and resolves with success: false instead.

Option	Type	Required	Notes
`pixelFormId`	`string` (UUID)	One of `pixelFormId` or `formId`	The id Default assigned when the form was approved on the Forms tab. It must belong to the domain tied to your public key, or the request 404s.
`formId`	`string`	One of `pixelFormId` or `formId`	The HTML `id` of the form. Use it if you do not use `pixelFormId`.
`responses`	`Record<string, string \| number \| boolean>`	Yes, at least one entry	The field values to submit.
`metadata`	`Record<string, unknown>`	No	Free-form data passed through to the submission event.
`autoDisplayScheduler`	`boolean \| { target: string \| HTMLElement; loader?: boolean }`	No	Overrides the default set on `init()` for this call only. With `{ target, loader: true }`, the branded loading indicator shows inside that container until the calendar loads. Omit `loader` or set it to `false` for no indicator. See The scheduler experience.

const result = await DefaultPixelSDK.submitForm({
  pixelFormId: "11111111-1111-4111-8111-111111111111",
  responses: {
    email: "jane@example.com",
    first_name: "Jane",
    plan: "growth",
    marketing_opt_in: true,
  },
  metadata: { source: "pricing-page", variant: "B" },
});

The return value:

Field	Type	Present when
`success`	`boolean`	Always
`status`	`number`	Always. It holds the HTTP status, and `0` means the request never reached Default
`scheduler`	`{ url: string }`	The workflow returned a scheduler handoff
`redirect`	`{ url: string }`	The workflow returned a redirect handoff. The browser navigates automatically the moment this happens, regardless of `autoDisplayScheduler`. You cannot suppress it, and this field is informational only
`workflow`	`{ executionStatus?, handoff?, error? }`	The submission reached Default
`error`	`string`	`success` is `false`

When multiple <form> elements are on the page, and you call submitForm({ pixelFormId, ... }) without also passing formId, the SDK guesses which DOM form you mean. The guess only enriches the submission with the form’s name, action, and class, and it never changes what gets submitted. The SDK picks the currently focused field’s form. If there is more than one form on the page, it picks a form tagged with a matching data-pixel-form-id or data-form-id attribute. To remove the ambiguity, pass formId explicitly or add one of those attributes. Your workspace’s form editor includes a live version of this call, pre-filled with your real public key, form id, and field names. To find it, open Forms, select a form, then open its Install tab, section Use the SDK. See Manual submission (the SDK) in the guide for how that sample relates to the initialization-timing guidance on this page.

recordFormInteraction

DefaultPixelSDK.recordFormInteraction(options). This method exists only on window.DefaultPixelSDK, and the Pixel (index.js) has no equivalent call. It manually mirrors the automatic email-blur warmup that powers pre-enrichment. Use it on hosts where the fields are not inside a native <form> element, so the SDK’s own listener has nothing to attach to. It never throws and swallows failures. The warmup is best-effort, not a required call.

Option	Type	Required	Default
`fieldName`	`string`	Yes	none
`fieldValue`	`string`	Yes	none
`formId`	`string`	No	none. The HTML `id` of the form. Reuse this value in `submitForm({ formId })` so the warmup and submission use the same cache key. Do not put the Pixel form UUID here.
`formName`	`string`	No	none
`fieldType`	`string`	No	`"email"`
`eventType`	`string`	No	`"focusout"`
`responses`	`Record<string, string>`	No	none. The SDK merges it with `{ [fieldName]: fieldValue }` for extra context

DefaultPixelSDK.recordFormInteraction({
  formId: "request-demo",
  fieldName: "email",
  fieldValue: "jane@example.com",
});

Use pixelFormId only with submitForm(). If you call both methods, use the same HTML form ID in both calls:

DefaultPixelSDK.recordFormInteraction({
  formId: "request-demo",
  fieldName: "email",
  fieldValue: "jane@example.com",
});

await DefaultPixelSDK.submitForm({
  pixelFormId: "11111111-1111-4111-8111-111111111111",
  formId: "request-demo",
  responses: { email: "jane@example.com" },
});

scheduler

DefaultPixelSDK.scheduler. A small object of typed helpers, all built on on() above.

Method	Equivalent to	Payload
`scheduler.onDisplayed(cb)`	`on("displayed", cb)`	`{ orgSlug, bookingParam }`
`scheduler.onClosed(cb)`	`on("closed", cb)`	none
`scheduler.onMeetingBooked(cb)`	`on("meeting_booked", cb)`	`{ meetingId, personEmail, startTime }`
`scheduler.onMeetingCancelled(cb)`	`on("meeting_cancelled", cb)`	`{ meetingId }`
`scheduler.onMeetingTimeout(cb)`	`on("meeting_timeout", cb)`	`{ meetingId? }`. Reserved, see the note below
`scheduler.display(url, option)`	Manually renders a scheduler URL you already have. It accepts the same modal, inline, and off behavior as `autoDisplayScheduler`	Returns a cleanup function

Each onX helper returns an unsubscribe function, same as on().

Scheduler events

Both on() and scheduler.onX react to messages that the embedded calendar posts. You can subscribe from either window.DefaultPixel or window.DefaultPixelSDK, because the two scripts share one event bus. Default validates each event against schedulerOrigins before your handler runs. It drops anything from an origin outside that list.

Event	Payload	Fires when
`displayed`	`{ orgSlug: string, bookingParam: string }`	The calendar has finished loading and is visible to the visitor
`closed`	none	The visitor closed the calendar without booking, or a terminal event auto-closed it
`meeting_booked`	`{ meetingId: string, personEmail: string, startTime: string }`	The visitor completed a booking
`meeting_cancelled`	`{ meetingId: string }`	The visitor cancelled a previously booked meeting from the calendar
`meeting_timeout`	`{ meetingId?: string }`	Reserved for a booking session timing out. We could not confirm from this snapshot whether the calendar currently sends this event. Treat it as defined but not yet guaranteed to fire

You can also close the calendar from your own code at any time, without waiting for a scheduler event:

window.postMessage("__default_scheduler_close__:re:null", "*");

What gets captured automatically

Whether a submission comes from automatic detection or submitForm(), Default fills in the same context fields for you:

Field	Source
Anonymous visitor id	A browser fingerprint, cached for a year in a first-party cookie and matching session storage entry. Falls back to a temporary random id if the fingerprint hasn’t resolved yet or fails.
Session id	A rolling 30-minute window. A new session starts if the visitor has been inactive longer than that.
UTM parameters	Read from the page’s query string at the moment of the request.
Google Ads click id (`gclid`)	Read from the page’s query string, omitted if absent.
User agent, page URL, referrer, timestamp	Standard browser values at the moment of the request.

Server contract (SDK submissions)

submitForm() posts to the same submission endpoint as automatically detected forms. Default tags the request so it can tell the two apart:

The request includes the Pixel form id when you passed pixelFormId. It also includes a marker that the submission came from the SDK rather than automatic detection.
If the form id doesn’t belong to the domain tied to your public key, the request fails with a 404.
The workflow attached to the form fires the same way it would for any other submission to that form.

Troubleshooting

See Troubleshooting in the integration guide for symptom-to-fix guidance, including the scheduler-latency issue this reference doesn’t repeat here.

Set up the Pixel and Forms SDK

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

Build a reliable Forms SDK flow

Apply the recommended initialization, submission, and scheduler pattern.

Understand the full integration

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

​Entry points

​Configuration

​Shared configuration options

​Methods

​init

​on

​submitForm

​recordFormInteraction

​scheduler

​Scheduler events

​What gets captured automatically

​Server contract (SDK submissions)

​Troubleshooting

​Related guides