Embed forms on your site
The one-line embed code, a pinned loader with an integrity check, the JavaScript and React SDKs, building your own form UI, and the server-side submission API.
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 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
Paste the "Paste on your site (one line)" code where the form should appear.
<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
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:
<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
After a submission, a sotto:submitted event fires on the script's parent element and on window. Use it for analytics tags and similar.
window.addEventListener("sotto:submitted", (event) => {
const { formId, submissionId } = event.detail;
});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.
<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
integrityvalue are published athttps://forms.sotto.la/embed-manifest.json.
JavaScript (@sotto/forms)
npm install @sotto/formsmount places the form inside an element.
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)
Works with React 18 or later.
npm install @sotto/forms-reactimport { 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
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.
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
}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
valuesare the field keys.definition.fieldsfromclient.load()(orformfromuseSottoForm) lists each field'skey,type,labelandrequired. statusfromuseSottoFormisloading,ready,submitting,submittedorerror.errorsmaps field keys to error codes, anderroris the error for the whole submission (networkwhen the connection drops).- Before sending, the SDK opens
https://forms.sotto.la/challengein 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)
To send submissions from your own server, use an API key. Never put an API key in browser code.
- An organization admin opens Settings > Security, goes to "API keys" and selects "Issue an API key".
- Under "What this key may do", choose "Submit to forms (from a server)", set "How long it works" and select "Issue".
- 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.
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-Keyis 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
valuesare the field keys. For a published form, check them indefinition.fieldsfromGET https://forms.sotto.la/api/v1/forms/<public ID>. - Add
contextto 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:
{
"ok": true,
"submissionId": "5b1d2c3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
"successMessage": "Thank you. Your submission has been received.",
"redirectUrl": null
}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
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
To deliver accepted submissions to your own system, use the "Send to webhook" routing action. See Receive form webhooks for the body and signature verification.