Forms

Embed a form widget, share a link, or submit and manage responses from your backend.

Build the form in the dashboard, then embed the widget on your site, send people the share link, or submit from your own backend with a secret key.

Embed the widget

<script src="https://app.softsolz.uk/softsolz.js"
  data-public-key="pk_live_your_key"
  data-service-id="forms"
  data-form-slug="your-form-slug"></script>

The widget handles multi-page forms, rules and calculations. Query parameters on the host page are passed to the form as pre-filled answers (matched to each question's URL name, then its id). When a form sends people on to a payment, a booking or a thank-you page, the widget asks the host page to navigate there.

Submit from your server

Send answers keyed by field id inside a data object. Choices with several answers are arrays, yes or no and consent answers are booleans, and address and grid answers are objects.

curl -X POST https://app.softsolz.uk/api/v1/services/forms/forms/contact-us/submit \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"data":{"email":"a@example.com","topics":["Pricing","Support"],"agree":true}}'

A 201 reply carries the submission id and success_message, plus redirect_url or next ({kind: "payment" | "booking", url}) when the form continues somewhere. Closed forms answer 410 form_closed and a reached daily limit answers 429 daily_limit_reached.

Drafts and publishing

A form has a draft and a published version. The widget, share link and submit endpoint always use the published version. Through the API, PATCH /forms/:id on a published form still publishes the change straight away, as before. Use POST /forms/:id/publish and POST /forms/:id/unpublish to control it explicitly, GET /forms/:id?view=published to read what visitors see, and has_unpublished_changes to spot a waiting draft.

Manage responses

List responses with status (new, in_progress, completed), archived, source and date filters, update them with PATCH /forms/:id/submissions/:subId (read, status, archived, assigned_to), add internal notes, and read per-form analytics with GET /forms/:id/analytics. The CSV export streams every row.

Webhook

forms.submission_received fires once per response from every channel. The payload carries submission_id, form_id, form_slug, form_name, submitted_at, source.kind (widget, link or api), the answers in data (also under values) and the linked contact_id. File answers carry the file name, type and size only; download files from the dashboard.