Create a form.

POSThttps://app.softsolz.uk/api/v1/services/forms/forms

Recent Requests

Kept only in this browser

TimeStatusTook

Send a request with Try it to see it here.

Headers

Authorizationstringrequired

Bearer token: `Bearer sk_live_...` (or `sk_test_...` for sandbox). A login token will not work here.

Idempotency-Keystring

Optional idempotency key for safe retries.

Body Params

namestringrequired

Form name (required, trimmed, at most 200 characters).

slugstring

Optional slug; cleaned to lowercase letters/digits/hyphens (the reply carries the cleaned slug). Defaults to a slugified name. Unique per tenant.

descriptionstring

Optional description (truncated to 1000 chars).

statusstring

Publish status; defaults to draft. Only published forms accept submissions, and publishing needs at least one field. Any other value is refused.

field_schemaarray of objects

Field definitions. Each item: { id, type, label, required?, width?, page?, help_text?, options?, accept?, max_size_mb?, ...type-specific keys }. Answer types: text, email, tel, url, number, textarea, select, radio, checkbox, checkbox_group, date, file, time, datetime, multi_select, yes_no, rating, scale, slider, likert, signature, address, country, consent, hidden, calculated. Layout items: heading, paragraph, divider, image, section.

settingsobject

Form settings; only known keys are persisted (success_message, redirect_url, submit_button_label, notify_in_app, honeypot_enabled, max_submissions_per_day, etc.).

appearanceobject

Appearance tokens (accent_color, theme, font_family, button_style, etc.).

themeobject

Optional legacy theme overrides.

logic_engineinteger

Rules engine version. New forms default to 2.

pagesarray of objects

Optional page titles for a multi-step form: { id, title?, description? }.

logicarray of objects

Optional rules. Rules that point at unknown fields or pages are dropped when saved.

Response

Response Body

idintegerForm id.

slugstringURL-safe form slug, unique per tenant.

namestringForm display name.

descriptionstring | nullOptional form description.

field_schemaarray of objectsOrdered field definitions. Each item: { id, type, label, required, width, ...type-specific keys }.

settingsobjectForm settings (success_message, notify_in_app, honeypot_enabled, etc.).

appearanceobjectAppearance tokens (colors, theme, font).

statusstringPublish status.

created_atstringCreation timestamp.

updated_atstringLast update timestamp. Round-trip as expected_updated_at to guard against stale writes.

created_byinteger | nullMember who created the form, when known.

created_by_namestring | nullName of the member who created the form.

submissions_countintegerTotal submissions for this form.

unread_countintegerUnread submissions.

pagesarray of objectsPage titles for a multi-step form, in order: { id, title?, description? }.

logicarray of objectsRules: { id, when: { match, rules: [{ field, operator, value }] }, then: [{ action, target?, value? }] }.

logic_engineintegerRules engine version. New forms use 2; older forms that only use visible_if may be 1.

published_atstring | nullWhen the live version was last published.

has_unpublished_changesbooleanTrue when the working copy differs from the published version.

archived_atstring | nullWhen the form was archived; null when it is not.

share_enabledbooleanWhether the share link is on.

version_idinteger | nullOnly with view=published: the published version id.

Request

curl --request POST \
  --url https://app.softsolz.uk/api/v1/services/forms/forms \
  --header 'Authorization: Bearer sk_live_your_key' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Contact Us",
  "slug": "contact-us",
  "description": "Reach our sales team.",
  "status": "published",
  "field_schema": [
    {
      "id": "full_name",
      "type": "text",
      "label": "Full name",
      "required": true
    }
  ],
  "settings": {
    "success_message": "Thanks, we got it!",
    "notify_in_app": true
  },
  "appearance": {
    "accent_color": "#2563eb",
    "theme": "light"
  },
  "theme": {},
  "logic_engine": 2,
  "pages": [
    {
      "id": "about_you",
      "title": "About you"
    }
  ],
  "logic": []
}'

Credentials

Authorization

Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.

Response · 201

{
  "data": {
    "id": 42,
    "slug": "contact-us",
    "name": "Contact Us",
    "description": "Reach our sales team.",
    "field_schema": [
      {
        "id": "full_name",
        "type": "text",
        "label": "Full name",
        "required": true
      }
    ],
    "settings": {
      "success_message": "Thanks!",
      "notify_in_app": true
    },
    "appearance": {
      "accent_color": "#2563eb",
      "theme": "light"
    },
    "status": "published",
    "created_at": "2026-06-01T12:00:00.000Z",
    "updated_at": "2026-06-02T09:30:00.000Z",
    "created_by": 7,
    "created_by_name": "Sam Lee",
    "submissions_count": 128,
    "unread_count": 4,
    "pages": [
      {
        "id": "about_you",
        "title": "About you"
      }
    ],
    "logic": [],
    "logic_engine": 1,
    "published_at": "2026-06-02T09:30:00.000Z",
    "has_unpublished_changes": false,
    "archived_at": null,
    "share_enabled": false,
    "version_id": 3
  }
}