Embed tax registration intake forms on your site

The Middesk JavaScript SDK lets you embed the tax registration intake flow directly in your application. Your users complete state and local tax registrations without leaving your site, while Middesk handles the form logic, jurisdiction requirements, and submission.

Before you begin

Make sure you have the following:

• A Middesk account with entity management enabled
• A publishable API key (prefixed pk_) — used in your frontend to initialize the SDK
• A secret API key (prefixed mk_) — used on your server to request passcodes
• Your domain registered as an allowed domain
• A passcode for the entity

Configure allowed domains

Register your application’s domain as an allowed domain before loading the SDK. Requests from unregistered domains are rejected.

To add an allowed domain, go to Developer > SDK Settings in the Middesk dashboard.

Get a passcode

The SDK requires a passcode to authenticate the session for a specific company. Retrieve one from your backend using the GET /v1/partner/passcode endpoint, authenticated with your secret API key.

The endpoint accepts either a company_id or an external_id query parameter to identify the company:

curl https://api.middesk.com/v1/partner/passcode?company_id=COMPANY_ID \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY'

The response includes a passcode field — pass this value as the passcode prop when creating the SDK component:

{
  "id": "passcode_id",
  "passcode": "PASSCODE",
  "expires_at": "2026-03-01T00:00:00.000Z",
  "url": "https://..."
}

Install the SDK

Add the Middesk SDK script to your page:

<script src="https://js.middesk.com/embed-sdk/v1/middesk.js"></script>

Set up the component

const middesk = new Middesk({ publishableKey: "pk_live_YOUR_PUBLISHABLE_KEY" });

const component = await middesk.createComponent({
  name: "tax-registration-intake",
  props: {
    passcode: "PASSCODE",
    highlighted_state: "NY"
  },
  onEvent: (event) => {
    console.log("SDK event:", event);
  }
});

const container = document.getElementById("middesk-container");
component.mount(container);
component.open();

<div id="middesk-container" style="width: 750px; height: 600px;"></div>

Full example

<div id="middesk-container" style="width: 750px; height: 600px;"></div>
<script src="https://js.middesk.com/embed-sdk/v1/middesk.js"></script>
<script>
  async function initMiddesk() {
    const middesk = new Middesk({
      publishableKey: "pk_live_YOUR_PUBLISHABLE_KEY"
    });
    const component = await middesk.createComponent({
      name: "tax-registration-intake",
      props: {
        passcode: "PASSCODE",
        highlighted_state: "NY"
      },
      onEvent: (event) => {
        console.log("SDK event:", event);
      }
    });
    const container = document.getElementById("middesk-container");
    component.mount(container);
    component.open();
  }
  initMiddesk();
</script>

Component props

Pass props to the intake component through the props object in createComponent.

When you set highlighted_state, the component selects and reorders the matching open registration request. If the state has no open request — because the code is unrecognized or that registration has already been submitted — the component falls back to selecting the first open request and leaves the list in its original order.

Handle events

The onEvent callback receives events from the component as the user interacts with the intake flow. Each event has the following shape:

READY

Emitted when the component has loaded and is ready for user interaction. No payload.

{
  "type": "READY",
  "componentName": "tax-registration-intake"
}

DONE

Emitted when the user has completed all outstanding tax registration requests. No payload.

{
  "type": "DONE",
  "componentName": "tax-registration-intake"
}

ERROR

Emitted when the component encounters an error. The payload includes an error object with a code and message.

{
  "type": "ERROR",
  "componentName": "tax-registration-intake",
  "payload": {
    "error": {
      "code": "LOAD_ERROR",
      "message": "Missing required props: passcode"
    }
  }
}

Example

onEvent: (event) => {
  switch (event.type) {
    case "READY":
      console.log("Component is ready");
      break;
    case "DONE":
      console.log("User completed all registrations");
      break;
    case "ERROR":
      console.error(event.payload.error.code, event.payload.error.message);
      break;
  }
}

Component lifecycle methods

The object returned by createComponent exposes the following methods:

Test in sandbox

Use the Middesk sandbox environment to test the embedded tax registration intake flow before going live.

curl https://api-sandbox.middesk.com/v1/partner/passcode?company_id=COMPANY_ID \
  -H 'Authorization: Bearer mk_test_YOUR_SECRET_KEY'

const middesk = new Middesk({
  publishableKey: "pk_test_YOUR_PUBLISHABLE_KEY"
});
const component = await middesk.createComponent({
  name: "tax-registration-intake",
  props: {
    passcode: "SANDBOX_PASSCODE",
    highlighted_state: "NY"
  },
  onEvent: (event) => {
    console.log("SDK event:", event);
  }
});