Form definitions

A form contains metadata plus a definition object:

{
  "id": "507f1f77bcf86cd799439011",
  "public_id": "contact-us",
  "workspace_id": "507f1f77bcf86cd799439012",
  "name": "Contact us",
  "status": "published",
  "is_closed": false,
  "definition": {
    "blocks": [],
    "settings": {},
    "theme": {},
    "variables": { "score": 0, "price": 0 },
    "hidden_fields": []
  }
}

Definition sections

Section	Behavior
`blocks`	Ordered questions and content blocks. Supplying this field replaces the complete block list.
`settings`	Form behavior such as navigation, branding, and closed state. Supplied keys are merged with existing settings.
`theme`	Colors, typography, layout, and other visual configuration. Supplied top-level keys are merged with the existing theme.
`variables`	Initial string or number values used by form logic. Available when creating the form.
`hidden_fields`	Unique names populated from matching form URL query parameters. Available when creating the form.

For updates, omitted blocks, settings, and theme sections remain unchanged. This makes it possible to update a form name or theme without resending its blocks. Variables and hidden fields are declared during creation in this API version.

Create a complete definition

Create a complete form by passing a definition to POST /v1/forms:

{
  "name": "Product feedback",
  "workspace_id": "507f1f77bcf86cd799439012",
  "type": "MULTI",
  "definition": {
    "blocks": [
      {
        "id": "rating",
        "type": "rating",
        "label": "How would you rate the product?",
        "description": "",
        "required": true,
        "properties": { "steps": 5 }
      },
      {
        "id": "comments",
        "type": "long-text",
        "label": "What could we improve?",
        "description": "",
        "required": false,
        "properties": { "maxChars": 2000 }
      },
      {
        "id": "ending",
        "type": "ending",
        "label": "Thank you",
        "description": "Your feedback has been recorded.",
        "required": false,
        "properties": { "buttonText": "Submit" }
      }
    ],
    "settings": {
      "progressBar": true,
      "navigation": true,
      "branding": true,
      "closed": false
    },
    "theme": {
      "font": "Inter",
      "corners": 0,
      "colors": {
        "primary": "#3969D9",
        "primaryForeground": "#FFFFFF"
      }
    },
    "variables": {
      "score": 0,
      "price": 0,
      "segment": "new-customer"
    },
    "hidden_fields": ["campaign_id", "account_id"]
  }
}

type is required. MULTI and SINGLE are available now. CONVERSATIONAL is reserved and returns 422 UNSUPPORTED_FORM_TYPE until that renderer is released. Do not send the old single_page field or write definition.settings.singlePage; the top-level type is authoritative.

Variables and hidden fields

Variable values can be strings or finite numbers. Names must start with a letter or underscore and may then contain letters, numbers, _, -, or .. A form can declare up to 100 variables. Onlyform always supplies score and price with a default value of 0 when you omit them. Hidden fields use the same naming rules. A form can declare up to 100 unique hidden fields. Pass values in the public form URL with matching query-parameter names, for example:

https://form.onlyform.com/contact-us?campaign_id=summer-2026&account_id=acct_123

The declarations are stored as form logic metadata. You do not need to add hidden-field question blocks for them.

variables and hidden_fields are create-only in the 2026-08-01 API contract. A later update containing either field returns 422 INVALID_DEFINITION_FIELD.

Block shape

Every block requires a stable id and supported type.

{
  "id": "customer-email",
  "type": "email",
  "label": "Email address",
  "description": "We will use this address to reply.",
  "required": true,
  "properties": {}
}

Block IDs are caller-supplied strings. Keep them stable across updates because submissions refer to fields by ID. Blocks may also contain:

choices for choice-based questions.
children for nested groups.
part_of for related display blocks.
row_id for blocks placed in the same row.
properties for type-specific settings.

The OpenAPI schema lists every supported block type.

Manage blocks directly

Use the focused block endpoints when you do not want to replace the rest of the form definition:

Operation	Purpose
`GET /v1/forms/{formId}/blocks`	List the ordered top-level block collection.
`POST /v1/forms/{formId}/blocks`	Add one block at an optional zero-based position.
`PUT /v1/forms/{formId}/blocks`	Replace or reorder the complete collection.
`GET /v1/forms/{formId}/blocks/{blockId}`	Read one top-level block.
`PUT /v1/forms/{formId}/blocks/{blockId}`	Fully replace and optionally move one block.
`DELETE /v1/forms/{formId}/blocks/{blockId}`	Remove one block.

Add a question at position 1:

curl --request POST \
  "https://api.onlyform.com/v1/forms/507f1f77bcf86cd799439011/blocks" \
  --header "X-API-Key: $ONLYFORM_API_KEY" \
  --header 'If-Match: "m5v8w7g0"' \
  --header "Content-Type: application/json" \
  --data '{
    "position": 1,
    "block": {
      "id": "company",
      "type": "short-text",
      "label": "Company",
      "description": "",
      "required": false,
      "properties": { "maxChars": 120 }
    }
  }'

To reorder several blocks atomically, fetch the latest collection and ETag, reorder the complete items array, then send it as blocks to PUT /v1/forms/{formId}/blocks with If-Match.

Focused block endpoints address top-level blocks. Nested questions are stored in a group block’s children array; replace that parent group to edit its nested collection.

Update a theme without changing content

curl --request PATCH \
  "https://api.onlyform.com/v1/forms/507f1f77bcf86cd799439011" \
  --header "X-API-Key: $ONLYFORM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "definition": {
      "theme": {
        "font": "Inter",
        "corners": 1,
        "colors": {
          "primary": "#3969D9",
          "primaryForeground": "#FFFFFF"
        }
      }
    }
  }'

Because blocks and settings are omitted, the request does not replace them.

Prevent lost updates with ETags

GET /v1/forms/{formId} returns an ETag header. Send that value as If-Match when updating the form:

curl --request PATCH \
  "https://api.onlyform.com/v1/forms/507f1f77bcf86cd799439011" \
  --header "X-API-Key: $ONLYFORM_API_KEY" \
  --header 'If-Match: "m5v8w7g0"' \
  --header "Content-Type: application/json" \
  --data '{"name":"Updated contact form"}'

If another request changed the form after you fetched it, Onlyform returns 412 FORM_VERSION_MISMATCH. Fetch the latest form, reconcile your change, and retry with the new ETag.

If you send definition.blocks, you replace the ordered block collection. Always start from the latest form and preserve every block you intend to keep.

Plan restrictions

API writes enforce the same plan limits as the dashboard. Features such as custom CSS, redirects, branding removal, payment fields, file uploads, signatures, gates, and maximum question counts may require a paid plan. A restricted change returns 403 PLAN_RESTRICTION.

Deletion behavior

DELETE /v1/forms/{formId} moves the form to trash and returns 204 No Content. It does not permanently remove the form.

Create a form

Create blocks, settings, a theme, variables, and hidden fields in one request.

Add a block

Add a question or content block without replacing the form.

Get started

Core concepts

API reference

Definition sections

Create a complete definition

Variables and hidden fields

Block shape

Manage blocks directly

Update a theme without changing content

Prevent lost updates with ETags

Plan restrictions

Deletion behavior

Create a form

Add a block

​Definition sections

​Create a complete definition

​Variables and hidden fields

​Block shape

​Manage blocks directly

​Update a theme without changing content

​Prevent lost updates with ETags

​Plan restrictions

​Deletion behavior

Create a form

Add a block

Definition sections

Create a complete definition

Variables and hidden fields

Block shape

Manage blocks directly

Update a theme without changing content

Prevent lost updates with ETags

Plan restrictions

Deletion behavior