> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.default.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Default Pixel and Forms SDK API reference

> Reference for every configuration option, method, return value, and scheduler event in the Default Pixel (index.js) and Forms SDK (sdk-core.js), with defaults.

This reference lists every option, method, return value, and scheduler event for the Default
Pixel (`index.js`) and Forms SDK (`sdk-core.js`).

A new install from **Settings → Domains** copies `core.js`, not `index.js`. `core.js` is form capture
and the scheduler, without page views. `index.js` is the older combined script that this page's
Pixel column describes; sites that already load it can keep it.

Read [Understand the Pixel and Forms SDK](https://docs.os.default.com/pixel-sdk-integration-guide.md) first to learn how the
Pixel and Forms SDK 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-core.js` |
| Example CDN URL | `https://handshake.default.com/index.js` | `https://handshake.default.com/sdk-core.js` |
| Global | `window.DefaultPixel` | `window.DefaultPixelSDK` |
| Programmatic API | `on()`, `scheduler.*`, and `submitForm()`, shared with the Forms SDK. It has no `init()`, no `recordFormInteraction()`, and no `setConsent()`. | The full set: `init`, `on`, `submitForm`, `recordFormInteraction`, `setConsent`, `scheduler.*`. |
| Auto-initializes from | `window.__defaultPixel__.key`, `.formsEndpoint`, `.schedulerOrigins`, `.autoDisplayScheduler`, and `.schedulerHandoffVerifyKey` | `window.__defaultPixel__` (all fields) |

Both scripts read scheduler configuration from the same block and post to 1 shared scheduler event
bus. `on()`, `scheduler.*`, and `submitForm()` therefore behave the same from either script.

See [Methods](#methods) below for exactly which methods live on which global.

```html theme={null}
<script>
  window.__defaultPixel__ = {
    key: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    // `endpoint` is read by the SDK (sdk-core.js) only.
    // `formsEndpoint` routes form requests through a separate proxy in both scripts.
    // schedulerOrigins and autoDisplayScheduler are read by both scripts.
    // endpoint: "https://api.default.com",
    // formsEndpoint: "https://forms.example.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.

The SDK applies `setConsent` calls queued on the generated Pixel loader, so a choice your banner
made before the SDK loaded still counts. See [Install the Forms SDK](https://docs.os.default.com/pixel-sdk-setup.md#install-the-forms-sdk).

`sdk.js`, the earlier Forms SDK file, still works with the same API. It also runs visitor
fingerprinting and session tracking, and it applies queued `setConsent` calls before it starts
tracking. When it shares a page with the Pixel, either script can load first, and a later
`window.__defaultPixel__.setConsent` call reaches both. To move to `sdk-core.js`, change only the
script address.

The Pixel (`index.js`) has no `init()` to call, but it reads `key`, `formsEndpoint`, `schedulerOrigins`,
`autoDisplayScheduler`, and `schedulerHandoffVerifyKey` 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. |
| `formsEndpoint` | `string` | No | The configured API endpoint | An HTTP(S) origin for form requests, such as a separate customer proxy. Both scripts read it, and form calls prefer it over `endpoint`. Existing form paths are preserved, including the legacy `/api/pixel/*` paths a form proxy already forwards. Tracking requests keep their normal 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. |
| `schedulerHandoffVerifyKey` | `string` | No | none | A base64 DER SPKI public key for verifying signed scheduler handoffs (ECDSA P-256). Set it on the page that receives the handoff, before the script loads. Without a key, a signed handoff that does not match the configured scheduler is rejected. Omitting it in a later `init()` call clears a key set earlier. This option does not make Default issue signed handoffs. Both scripts read it. |
| `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. |

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

The Pixel (`index.js`) has no equivalent `init()` call. Its tracking requests use Default's standard
endpoint. Set `window.__defaultPixel__.formsEndpoint` before loading the script to send form requests
through a separate proxy, such as when the tracking host is blocked. The proxy must forward the
existing form routes, including `/api/pixel/*`; changing the host does not rename those paths.

It also reads `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](https://docs.os.default.com/pixel-sdk-integration-guide.md#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`, `recordFormInteraction`, and `setConsent` 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 attaches the email-blur
listener that powers pre-enrichment. The Forms SDK does no identity or session tracking of its own; see
[What gets captured automatically](#what-gets-captured-automatically).

The start also checks for a pending scheduler handoff left over from a same-page redirect. The method
returns nothing.

See [Shared configuration options](#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.

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

`eventType` is one of the 5 values in [Scheduler events](#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](#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 added in **Forms**. It must be active and belong to the workspace tied to your public key, or the request returns 404. An explicit ID can name a form on another connected domain in that workspace. Page restrictions still apply. |
| `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 \| string[] \| null>` | Yes, at least 1 non-null entry | The field values to submit. Use the configured field names and types. A `null` value means the field was left unanswered. Default drops it, treating it like an omitted field; it never clears a saved value. |
| `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](https://docs.os.default.com/pixel-sdk-integration-guide.md#the-scheduler-experience). |
| `theme` | `"light" \| "dark" \| "auto"` | No | Which look the calendar opens in. `light` or `dark` forces that look. `auto`, or leaving it out, follows the visitor's device setting. The loading indicator uses the same look, and `result.scheduler.url` carries it as `theme=...`, so a host that mounts its own iframe gets the same look. Each look's colors are set in **Settings → Scheduling → Appearance**. |
| `background` | `"card" \| "transparent"` | No | `transparent` leaves the calendar's card unpainted so a popup you render yourself shows through, blur and all. Only an inline embed honours it (`autoDisplayScheduler: { target }`, or your own iframe loading `result.scheduler.url` with `embed_layout=inline`); the full-screen modal keeps its dim and card. Pair it with `theme` so the text matches your popup. Stamped on `result.scheduler.url` as `embed_background=transparent`. |

```ts theme={null}
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:

`outcome: "pending"` means the submission attempt is still processing after the SDK finishes waiting.
This result has `success: false`, even when `status` is `200`. Check `outcome` before treating
`!result.success` as a failed submission. This differs from `workflowOutcome.outcome`, which describes
workflow progress.

The pending result includes `submissionId`, the ID of this attempt. The SDK reuses this ID for its
automatic retries and pending checks. It is not the ID of a saved submission record. Automatic
checks stop when the call returns, and the public SDK has no method to resume them. Keep repeat
submission blocked and show a processing message. Calling `submitForm()` again creates a new attempt
and can duplicate the submission.

`success: true` means the request completed. It does not prove a submission was saved or a workflow
ran. A form with submissions disabled, or a page outside its allowed paths, can return success.
Read `submission` and `workflowOutcome` to see whether Default accepted the submission and whether
it started a workflow. `accepted` confirms the server accepted the submission for processing. The API normally waits for event publication. When it returns a scheduler or redirect handoff,
or reaches the realtime workflow wait deadline, publication can finish in the background. Downstream processing and visibility can lag either response. Check **Recent Submissions** to confirm a
submission was recorded. Against an older API `submission` and `workflowOutcome` are absent, so check
**Recent Submissions** and the workflow's result there too.

| Field | Type | Present when |
| - | - | - |
| `success` | `boolean` | Always |
| `status` | `number` | Always. It holds the HTTP status. `0` means no usable HTTP response was received; the request may still have reached Default |
| `scheduler` | `{ url: string }` | The workflow returned a scheduler handoff. The URL is ready to load in an iframe and carries the `theme` you passed, if any |
| `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 |
| `submission` | `{ outcome: "accepted" }` or `{ outcome: "skipped", reason }` | The API reports what it did with the submission. `reason` is `submissions_disabled`, `page_not_allowed`, `form_unresolved`, or `blocked` (the visitor's email domain is on the workspace's blocked list; nothing was saved). Absent against an older API |
| `workflowOutcome` | `{ outcome, reason? }` | The API reports whether it started a workflow. `outcome` is `dispatched`, `pending` (the workflow was still running when the response returned), `skipped`, or `error`. A skipped outcome carries `reason` `no_valid_email` or `no_workflow_dispatched`. Absent against an older API |
| `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 1 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 **Embed** tab
(**SDK** for a Pardot form), section **Use the SDK**.

See [Manual submission (the SDK)](https://docs.os.default.com/pixel-sdk-integration-guide.md#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.

It does nothing while analytics consent is declined and checks consent again on each call.
Form submissions still work and run enrichment normally.

| Option | Type | Required | Default |
| - | - | - | - |
| `fieldName` | `string` | Yes | none |
| `fieldValue` | `string` | Yes | none |
| `pixelFormId` | `string` (UUID) | No | none. The saved form UUID used by `submitForm({ pixelFormId })`. Pass it for a custom form without a matching HTML ID so Default can resolve the saved form for the warmup. |
| `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 |
| `formType` | `string` | No | `"html"`. The vendor rendering the form, such as `"hubspot"` or `"marketo"`. |
| `fieldType` | `string` | No | `"email"` |
| `eventType` | `string` | No | `"focusout"` |
| `responses` | `Record<string, string>` | No | none. The SDK merges it with `{ [fieldName]: fieldValue }` for extra context |

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

Pass the same saved UUID as `pixelFormId` to both methods. If the form also has an HTML ID, pass the
same `formId` in both calls so either identifier can connect the warmup to the submission:

```ts theme={null}
await DefaultPixelSDK.recordFormInteraction({
  pixelFormId: "11111111-1111-4111-8111-111111111111",
  formId: "request-demo",
  formType: "html",
  fieldName: "email",
  fieldValue: "jane@example.com",
});

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

### setConsent

`DefaultPixelSDK.setConsent(consent)`. This method exists only on `window.DefaultPixelSDK`, and the Pixel
(`index.js`) has no equivalent call. On the Pixel, use `window.__defaultPixel__.setConsent` instead.

`consent` is `Partial<{ analytics: boolean; marketing: boolean }>`. Pass only the categories that
changed; a category you leave out keeps its saved value, or allowed if the visitor never chose.
The choice is saved in the `_dflt_consent` cookie, so it applies to later pages and to the Pixel.
Withholding `analytics` also drops the identifiers the SDK stored in the tab. The Forms SDK loads no
Vector script, so `marketing` is saved but changes nothing in it. The method returns nothing.

```ts theme={null}
DefaultPixelSDK.setConsent({ analytics: false });
```

A `setConsent` call your banner made through `window.__defaultPixel__.setConsent` before the SDK
loaded is applied for you. See [Shared configuration options](#shared-configuration-options).

### 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.onSlotsReady(cb)` | `on("slots_ready", cb)` | `{ orgSlug, bookingParam, workflowExecutionId? }` |
| `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, handoffConfig?, presentation?)` | Manually renders a scheduler URL you already have. It accepts the same modal, inline, and off behavior as `autoDisplayScheduler`. `handoffConfig` takes the booking redirects and `hideClose` from a `submitForm()` result. `presentation.theme` (`"light"`, `"dark"`, `"auto"`) picks the look and `presentation.background: "transparent"` leaves an inline card unpainted, the same way as the `theme` and `background` options of `submitForm()` | 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 2 scripts share 1 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 is visible to the visitor. It also fires after a 10 second fallback when no times have loaded, so do not time readiness with it |
| `availability_changed` | `{ orgSlug: string, bookingParam: string, workflowExecutionId?: string, availabilityState: 'loading' \| 'empty' \| 'error' \| 'ready' }` | Availability diagnostics after the initial display. Does not emit another `displayed` callback or establish clickability |
| `slots_ready` | `{ orgSlug: string, bookingParam: string, workflowExecutionId?: string }` | A visible appointment time accepts a click. Fires once per scheduler document and never for an empty or failed availability result. Use it to measure submit to clickable time; `workflowExecutionId` joins it to the form submission that opened the calendar |
| `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 |

## What gets captured automatically

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

The visitor and session ids depend on which script sent the submission. With analytics denied,
neither script saves a visitor identifier.

| Field | The Pixel (`index.js`) | The Forms SDK (`sdk-core.js`) |
| - | - | - |
| 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. | The Pixel's visitor id when the Pixel has stored one and analytics is allowed, so the submission joins that visitor's page views. Otherwise a random id kept for the browser tab, or a new one per submission when analytics is denied. |
| Session id | A rolling 30-minute window. A new session starts if the visitor has been inactive longer than that. | The Pixel's current session when it is loaded and analytics consent allows; form activity renews an expired session so warmups and submissions agree. Otherwise a stored live analytics session or a random id kept for the browser tab. |
| UTM parameters | The page's query string at the moment of the request when it carries any. Otherwise the visitor's latest stored campaign landing, which is kept for 180 days when analytics is allowed. | Same. |
| Google Ads click id (`gclid`) | Same rule as the UTM parameters, omitted if absent. | Same. |
| Referrer | The page's `document.referrer` when it is another website. Otherwise an outside referrer stored earlier, when analytics is allowed. | Same. |
| User agent, page URL, timestamp | Standard browser values at the moment of the request. | Same. |
| HTTP status of the page | The status the page was served with, when the browser reports it. Later client-side route changes do not update it. | Same. |
| Browser language, time zone, and touch points | The browser's language setting, the time zone of the device clock, and the number of touch points the device reports, read once per page. Sent regardless of the analytics choice, like the IP address. | Same. |
| Country, region, city, device type | Added by Default when the submission arrives: location from the visitor's IP address, device type from the browser. | Same. |

## Server contract (SDK submissions)

`submitForm()` posts to the same submission endpoint as automatically detected forms. Default tags the
request so it can tell the 2 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.
* An explicit `pixelFormId` must name an active form in the workspace tied to your public key.
  Otherwise the request fails with a 404. Matching by HTML `formId` is limited to the page's domain.
* Default only saves accepted submissions from allowed pages. Published workflows attached to that
  form can then run.

## Troubleshooting

See [Troubleshooting](https://docs.os.default.com/pixel-sdk-integration-guide.md#troubleshooting) in the integration guide
for symptom-to-fix guidance, including the scheduler-latency issue this reference doesn't repeat here.

## Related guides

> [card] [Set up the Pixel and Forms SDK](https://docs.os.default.com/pixel-sdk-setup.md)
>
> Connect a domain, add a form, install the SDK, and verify a workflow.

> [card] [Build a reliable Forms SDK flow](https://docs.os.default.com/pixel-sdk-best-practices.md)
>
> Apply the recommended initialization, submission, and scheduler pattern.

> [card] [Understand the full integration](https://docs.os.default.com/pixel-sdk-integration-guide.md)
>
> Learn how identity, form capture, workflows, and scheduler handoffs work together.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.