# Embed forms on your site (/docs/en/forms-embed)

Share a published form by its URL, or embed it on your own site. The code appears under "Embed on your site" on the form's "Publish" tab, already filled in with the form's public ID (starting with `frm_`). See [Create and publish forms](/docs/en/forms) for publishing.

| Method | Use it when |
|---|---|
| One-line embed code | You want to paste the form into HTML |
| Pinned version | You want an integrity check (SRI) on the script you load |
| JavaScript (`mount`) / React (`<SottoForm>`) | You want the form in a specific place in your app |
| Your own UI (`createFormClient` / `useSottoForm`) | You want to build the inputs with your own design |
| API | You want to send submissions from your own server |

Submissions from every method go through the same spam protection, import and routing. The submission detail shows the channel it came from (form page, embed, SDK or API).

## One-line embed code [#one-line-embed-code]

Paste the "Paste on your site (one line)" code where the form should appear.

```html
<script async src="https://forms.sotto.la/embed.js" data-sotto-form="frm_8FqK2mZp4XbN"></script>
```

- The form is inserted right before the script. You can place several forms on one page.
- The form's height adjusts to its content automatically.
- The page URL, UTM parameters (queries starting with `utm_`) and referrer are added to the submission. You can use them in routing conditions, and they're kept on the submission.
- Sotto ships improvements to `embed.js`, so its content changes. For an integrity check, use the pinned version below.

### Pass hidden values [#pass-hidden-values]

When a "Hidden value" field uses "Passed by the embedding page" as its source, pass the value with `data-sotto-hidden-<name passed by the page>`. With the name `plan`:

```html
<script async src="https://forms.sotto.la/embed.js" data-sotto-form="frm_8FqK2mZp4XbN" data-sotto-hidden-plan="team"></script>
```

Fields whose source is "URL query" or "UTM" read the URL of the page where the form is placed automatically.

### Know when a submission is sent [#know-when-a-submission-is-sent]

After a submission, a `sotto:submitted` event fires on the script's parent element and on `window`. Use it for analytics tags and similar.

```js
window.addEventListener("sotto:submitted", (event) => {
  const { formId, submissionId } = event.detail;
});
```

## Pinned version (with integrity check) [#pinned-version-with-integrity-check]

The "Pin the version (with integrity check)" code loads a loader version whose content never changes, with an `integrity` attribute.

```html
<script async src="https://forms.sotto.la/embed/v1.js" data-sotto-form="frm_8FqK2mZp4XbN" integrity="sha384-…" crossorigin="anonymous"></script>
```

- A pinned version never changes. Improvements ship as a new version number, and old versions stay available.
- The latest pinned version's path and `integrity` value are published at `https://forms.sotto.la/embed-manifest.json`.

## JavaScript (@sotto/forms) [#javascript-sottoforms]

```bash
npm install @sotto/forms
```

`mount` places the form inside an element.

```ts
import { mount } from "@sotto/forms";

const handle = mount(document.getElementById("contact")!, {
  form: "frm_8FqK2mZp4XbN",
  hidden: { plan: "team" },
  onReady: () => {},
  onSubmitted: ({ formId, submissionId }) => {},
  onError: ({ code }) => {},
});

// Remove it from the page
handle.destroy();
```

On pages without a bundler, load `https://forms.sotto.la/sdk/v1/sotto-forms.js` and use `mount` and `createFormClient` from `window.SottoForms`.

## React (@sotto/forms-react) [#react-sottoforms-react]

Works with React 18 or later.

```bash
npm install @sotto/forms-react
```

```tsx
import { SottoForm } from "@sotto/forms-react";

export function Contact() {
  return (
    <SottoForm
      form="frm_8FqK2mZp4XbN"
      hidden={{ plan: "team" }}
      onSubmitted={({ submissionId }) => console.log(submissionId)}
    />
  );
}
```

`onReady`, `onError` and `className` are also available.

## Build your own UI [#build-your-own-ui]

To build the inputs with your own design, use `createFormClient` (or `useSottoForm` in React). Validation follows the same rules as the server, and the SDK handles the bot check and sending.

```ts
import { createFormClient } from "@sotto/forms";

const client = createFormClient({ form: "frm_8FqK2mZp4XbN" });
const form = await client.load(); // title, fields and text
const values = { email: "taro@example.jp", message: "Please send the materials" };

const errors = client.validate(values); // empty array when valid
const result = await client.submit(values, { hidden: { plan: "team" } });
if ("error" in result) {
  // result.error.code, plus result.error.fields (key and code) per field
} else {
  // result.successMessage / result.redirectUrl
}
```

```tsx
import { useSottoForm } from "@sotto/forms-react";

export function ContactForm() {
  const { form, values, setValue, errors, status, submit } = useSottoForm("frm_8FqK2mZp4XbN");
  if (!form) return null;
  if (status === "submitted") return <p>{form.definition.successMessage}</p>;
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        void submit();
      }}
    >
      <input
        value={String(values.email ?? "")}
        onChange={(event) => setValue("email", event.target.value)}
      />
      {errors.email ? <p>{errors.email}</p> : null}
      <button type="submit" disabled={status === "submitting"}>
        {form.definition.submitLabel}
      </button>
    </form>
  );
}
```

- The keys of `values` are the field keys. `definition.fields` from `client.load()` (or `form` from `useSottoForm`) lists each field's `key`, `type`, `label` and `required`.
- `status` from `useSottoForm` is `loading`, `ready`, `submitting`, `submitted` or `error`. `errors` maps field keys to error codes, and `error` is the error for the whole submission (`network` when the connection drops).
- Before sending, the SDK opens `https://forms.sotto.la/challenge` in an invisible iframe to check for bots. Usually nothing is visible; only when interaction is needed does a small check appear at the bottom right of the page. You don't need to register your domain or anything else.
- Retrying the same submission keeps it as one submission until it is accepted.

`client.load()` throws `SottoFormsError` (with a `code`) when, for example, the form isn't found. `client.submit()` returns the error codes listed under "Errors" below as values and throws only when the connection drops or the response is unexpected.

## Send from the API (server side) [#send-from-the-api-server-side]

To send submissions from your own server, use an API key. **Never put an API key in browser code.**

1. An organization admin opens Settings > Security, goes to "API keys" and selects "Issue an API key".
2. Under "What this key may do", choose "Submit to forms (from a server)", set "How long it works" and select "Issue".
3. Copy the key. It's never shown again once you close the dialog.

A key can only submit to forms in the workspace it was issued for.

```bash
curl -X POST https://forms.sotto.la/api/v1/forms/frm_8FqK2mZp4XbN/submissions \
  -H "Authorization: Bearer $SOTTO_API_KEY" \
  -H "Idempotency-Key: 5f0c1f7e-2b8a-4d0e-9a51-7c3e2d9b8f10" \
  -H "Content-Type: application/json" \
  -d '{"values":{"email":"taro@example.jp","message":"Please send the materials"}}'
```

- `Idempotency-Key` is required (8–200 characters). Sending again with the same key returns the first result without creating a new submission. Use a new key for each submission and the same key when retrying.
- The keys of `values` are the field keys. For a published form, check them in `definition.fields` from `GET https://forms.sotto.la/api/v1/forms/<public ID>`.
- Add `context` to include UTM values and more: `{"utm": {"utm_source": "partner"}, "referrer": "https://…", "sourceUrl": "https://…", "locale": "en"}`.
- The body can be up to 64 KB.
- Submissions sent with an API key skip the browser bot check. The other protections (disposable email addresses, duplicates and the AI spam check) apply as usual.

A successful response:

```json
{
  "ok": true,
  "submissionId": "5b1d2c3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "successMessage": "Thank you. Your submission has been received.",
  "redirectUrl": null
}
```

### Errors [#errors]

Errors come back as `{"error": {"code": "…", "message": "…", "fields": […]}}`. `fields` is included only for `invalid_fields` and lists a reason per field, such as `[{"key": "email", "code": "invalid_email"}]`.

| Status | code | Meaning |
|---|---|---|
| 400 | `invalid_request` | The body is malformed, larger than 64 KB, or `Idempotency-Key` is missing |
| 400 | `invalid_fields` | Input breaks a field rule (`required`, `invalid_email`, `too_long`, `disposable_email` and so on) |
| 400 | `session_expired` | Browser submissions only: the page expired (the SDK reloads and resends automatically) |
| 400 | `challenge_failed` | Browser submissions only: the bot check couldn't be completed |
| 401 | `unauthorized` | The API key is invalid, expired or revoked |
| 403 | `unauthorized` | The API key can't submit to forms, or a browser submission came from a site not in the allowed sites |
| 404 | `not_found` | The form doesn't exist, isn't published, or belongs to a different workspace than the key |
| 409 | `paused` | The form isn't accepting submissions, or was stopped by Sotto |
| 429 | `over_limit` | Too many submissions right now. Try again later |

## Limit the sites that can embed the form [#limit-the-sites-that-can-embed-the-form]

Enter sites like `https://example.com` (up to 20) under "Sites that can embed the form" on the "Spam protection" tab. Leave it empty to allow any site. With sites listed:

- The embedded form appears only on the listed sites.
- Browser submissions and bot checks work only from the listed sites.
- Server submissions with an API key aren't affected.

Changes apply after you publish again.

If your site sets a Content-Security-Policy, add `https://forms.sotto.la` to `script-src` (loading `embed.js` and the SDK), `frame-src` (the form and the check frame) and `connect-src` (submissions from `createFormClient` and `useSottoForm`).

## Receive submissions in your own system [#receive-submissions-in-your-own-system]

To deliver accepted submissions to your own system, use the "Send to webhook" routing action. See [Receive form webhooks](/docs/en/webhooks) for the body and signature verification.