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

# Client-side API

> Use window.OCT to send custom form submissions, update consent manually, and debug the pixel.

Use the client-side API when the normal pixel form detection is not enough and you need to trigger Octanist from your own browser JavaScript.

Do not use this page for server-side API calls. API keys must stay on your server. For backend form submissions, use [Server-side form capture](/docs/incoming-integrations/server-side-capturing).

## Before you start

Install the Octanist pixel on the page first:

```html theme={null}
<script
  src="https://c.octani.st/p"
  data-id="OCT-XXXXXXXX"
  data-consent-mode="auto"
></script>
```

If you send the same form manually with `window.OCT.submitLeadForm`, prevent automatic browser capture for that form with `data-octa-ignore`.

```html theme={null}
<form data-octa-ignore>
  <!-- fields -->
</form>
```

This keeps the pixel active for page views, sessions, consent, and `octa_sid`, while preventing the same form from being captured twice.

## Send a form submission

Use `window.OCT.submitLeadForm(fields, options)` after your form has successfully submitted.

```js theme={null}
window.OCT.submitLeadForm(
  {
    name: "John Doe",
    email: "john@example.com",
    phone: "+31612345678",
    company: "Example BV",
  },
  {
    formIdentifier: "contact-form",
  },
);
```

The method returns `true` when Octanist accepted the payload for sending. It returns `false` when the payload is empty or invalid.

Supported options:

| Option           | Description                                                                           |
| ---------------- | ------------------------------------------------------------------------------------- |
| `formIdentifier` | A stable name for the form, such as `contact-form` or `demo-request`.                 |
| `path`           | Optional page path override. Use only when the form belongs to a different page path. |
| `title`          | Optional page title override.                                                         |

Octanist ignores sensitive fields such as passwords, captcha tokens, card fields, CSRF tokens, and `octa_sid`. Field values are trimmed and long values are shortened.

## AJAX example

For AJAX forms, send the form to your own endpoint first. Call Octanist only after the website knows the form was accepted.

```js theme={null}
async function submitForm(form) {
  const formData = new FormData(form);

  const response = await fetch("/contact", {
    method: "POST",
    body: formData,
  });

  if (!response.ok) return;

  window.OCT.submitLeadForm(
    {
      name: formData.get("name"),
      email: formData.get("email"),
      phone: formData.get("phone"),
      message: formData.get("message"),
    },
    {
      formIdentifier: "contact-form",
    },
  );
}
```

## Read the session ID

Use `window.OCT.getSessionId()` when you need the browser session ID.

```js theme={null}
const sessionId = window.OCT.getSessionId();
```

This is the same value the pixel injects into forms as `octa_sid`.

## Update consent manually

Use `window.OCT.setConsent()` when your consent banner has its own callback and Octanist cannot detect it automatically.

```js theme={null}
window.OCT.setConsent({
  analytics: true,
  marketing: true,
  source: "custom_banner",
});
```

To revoke consent:

```js theme={null}
window.OCT.setConsent({
  analytics: false,
  marketing: false,
  source: "custom_banner",
});
```

When consent changes from denied to granted, Octanist upgrades the session and stores the consent state. When consent is revoked, Octanist records the downgrade and removes the visitor cookie.

## Set consent before OCT is ready

If your consent code can run before the pixel has finished loading, use one of these options.

Set a global value before the pixel loads:

```html theme={null}
<script>
  window.octanistConsent = {
    analytics: true,
    marketing: true,
  };
</script>
```

Or dispatch an event when your consent banner changes:

```js theme={null}
window.dispatchEvent(
  new CustomEvent("octanist:consent", {
    detail: {
      analytics: true,
      marketing: true,
    },
  }),
);
```

## Other OCT methods

| Method                                       | Description                                                             |
| -------------------------------------------- | ----------------------------------------------------------------------- |
| `window.OCT.getSessionId()`                  | Returns the current session ID.                                         |
| `window.OCT.getClientId()`                   | Returns the visitor cookie ID when consent allows it, otherwise `null`. |
| `window.OCT.getConsentState()`               | Returns the current consent state.                                      |
| `window.OCT.setConsent(consent)`             | Manually updates consent.                                               |
| `window.OCT.submitLeadForm(fields, options)` | Sends a browser-side form submission.                                   |
| `window.OCT.debug()`                         | Returns a debug snapshot for the current page.                          |

Example debug snapshot:

```js theme={null}
console.log(window.OCT.debug());
```

## Debugging

Use `window.OCT.debug()` for a quick browser console snapshot. For a fuller support report, use the [Octanist Debugger](/docs/troubleshooting/octanist-debugger).