# Surface Forms SDK



The Forms SDK lets you build a Surface form as a page you own. The form record on Surface stays the data model; your HTML, CSS, and JavaScript control how the form looks and how visitors move through it. Unlike [embedding](/platform/forms/embedding/inline), Surface never sees or serves your markup, but still receives every response, partial save, booking, and analytics event.

## What You Get [#what-you-get]

<CardGroup cols="2">
  <Card title="Your Markup, Bound with Data Attributes" icon="code">
    `data-question-id` and friends; the SDK captures answers and saves progress.
  </Card>

  <Card title="Headless Engine and React Hook" icon="react">
    Drive everything from code, or use `useSurfaceForm`. Also runs in Node.
  </Card>

  <Card title="Embedded Schedulers" icon="calendar-check">
    One call renders any supported provider; bookings save automatically.
  </Card>

  <Card title="Tracking and Attribution Built In" icon="chart-line">
    GTM, GA4, Meta Pixel, HubSpot, and ad conversions fire from the form's settings.
  </Card>

  <Card title="Email Validation and Enrichment" icon="user-check">
    Deliverability verdicts and real-time lead enrichment.
  </Card>

  <Card title="Built for AI-assisted Authoring" icon="wand-magic-sparkles">
    The MCP server creates the record, hands over the binding contract, and validates the HTML.
  </Card>
</CardGroup>

Published as [`@surface-labs/forms-sdk`](https://www.npmjs.com/package/@surface-labs/forms-sdk) on npm. About 22 kB gzipped, zero runtime dependencies, and every request is a CORS simple request (no preflights).

## How It Works [#how-it-works]

1. **The form record lives on Surface**, created in the dashboard's SDK form builder or with the [MCP tools](/build/forms-sdk/building-with-ai). It declares steps, questions, answer shapes, and endings; styling and routing belong to your page.
2. **Your page binds to the record.** `SurfaceForms.init` fetches the runtime configuration; the `data-*` layer captures answers from your inputs, or your code sets them directly.
3. **The SDK writes responses.** Partial saves run in the background; the finishing write on submit is awaited.

```js
import { SurfaceForms } from "@surface-labs/forms-sdk";

const form = await SurfaceForms.init({
  environmentId: "env_xxx",
  formId: "form_xxx",
  apiBaseUrl: "https://forms.withsurface.com", // your environment's host
  container: document.querySelector("#form"),
});
```

## When to Use the SDK [#when-to-use-the-sdk]

| Use case                                                                 | Recommendation                                           |
| ------------------------------------------------------------------------ | -------------------------------------------------------- |
| A form that must match your site's design system exactly                 | Forms SDK                                                |
| A form inside a React, Vue, or Svelte app with its own state and routing | Forms SDK                                                |
| Conditional flow logic that lives in your codebase                       | Forms SDK                                                |
| A standard form live in minutes with the visual builder                  | [Hosted form or embed](/platform/forms/embedding/inline) |
| A marketing pane, hosted URL, custom domain, or A/B-ready styling        | Hosted form or embed                                     |

SDK forms skip hosted-page settings (language, custom domain, password, SEO, Turnstile). Responses, workflows, analytics, lead scoring, and integrations work the same as any other Surface form.

## Documentation Map [#documentation-map]

<CardGroup cols="2">
  <Card title="Quickstart" icon="rocket" href="/build/forms-sdk/quickstart">
    A working form on your page.
  </Card>

  <Card title="Binding Contract" icon="list-check" href="/build/forms-sdk/binding">
    The data attribute vocabulary.
  </Card>

  <Card title="Navigation" icon="diagram-project" href="/build/forms-sdk/navigation">
    Buttons, branching, and submit semantics.
  </Card>

  <Card title="Headless and React" icon="react" href="/build/forms-sdk/headless-and-react">
    The form handle API and the React adapter.
  </Card>

  <Card title="Schedulers" icon="calendar-check" href="/build/forms-sdk/schedulers">
    Embedded booking for every provider.
  </Card>

  <Card title="Building with AI" icon="wand-magic-sparkles" href="/build/forms-sdk/building-with-ai">
    The MCP authoring loop.
  </Card>
</CardGroup>

<Note>
  The npm package ships agent-ready docs (`llms.txt`, `docs/api.md`) and an installable skill in `skills/surface-forms-sdk/`.
</Note>