Surface Forms SDK
Build Surface forms as your own pages: your HTML and CSS, Surface's data model, validation, scheduling, enrichment, and tracking
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 own every pixel and every navigation decision. Unlike embedding, Surface never sees or serves your markup, yet still gets every response, partial save, booking, and analytics event.
What you get
Your markup, bound with data attributes
data-question-id and friends; the SDK captures answers and saves progress.
Headless engine and React hook
Drive everything from code, or use useSurfaceForm. Also runs in Node.
Embedded schedulers
One call renders any supported provider; bookings save automatically.
Tracking and attribution built in
GTM, GA4, Meta Pixel, HubSpot, and ad conversions fire from the form's settings.
Email validation and enrichment
Deliverability verdicts and real-time lead enrichment.
Built for AI-assisted authoring
The MCP server creates the record, hands over the binding contract, and validates the HTML.
About 22 kB gzipped, zero runtime dependencies, and every request is a CORS simple request (no preflights).
How it works
- The form record lives on Surface, created in the dashboard's SDK form builder or with the MCP tools. It declares steps, questions, answer shapes, and endings; styling and routing belong to your page.
- Your page binds to the record.
SurfaceForms.initfetches the runtime configuration; thedata-*layer captures answers from your inputs, or your code sets them directly. - The SDK writes responses. Partial saves run in the background; the finishing write on submit is awaited.
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
| 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 |
| 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
Quickstart
A working form on your page.
Binding contract
The data attribute vocabulary.
Navigation
Buttons, branching, and submit semantics.
Headless and React
The form handle API and the React adapter.
Schedulers
Embedded booking for every provider.
Building with AI
The MCP authoring loop.
The npm package ships agent-ready docs (llms.txt, docs/api.md) and an installable skill in skills/surface-forms-sdk/.