Client-side API

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.

Before you start

Install the Octanist pixel on the page first:

<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.

<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.

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.

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.

const sessionId = window.OCT.getSessionId();

This is the same value the pixel injects into forms as octa_sid. Use window.OCT.setConsent() when your consent banner has its own callback and Octanist cannot detect it automatically.

window.OCT.setConsent({
  analytics: true,
  marketing: true,
  source: "custom_banner",
});

To revoke consent:

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. 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:

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

Or dispatch an event when your consent banner changes:

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:

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.

Get Started

Website installation

Integrations

Advanced setup

Troubleshooting

Before you start

Send a form submission

AJAX example

Read the session ID

Other OCT methods

Debugging

​Before you start

​Send a form submission

​AJAX example

​Read the session ID

​Update consent manually

​Set consent before OCT is ready

​Other OCT methods

​Debugging

Before you start

Send a form submission

AJAX example

Read the session ID

Update consent manually

Set consent before OCT is ready

Other OCT methods

Debugging