Variables and hidden fields

Variables and hidden fields are available on Free and paid plans. Declare them in definition when calling POST /v1/forms.

{
  "name": "Lead qualification",
  "workspace_id": "507f1f77bcf86cd799439012",
  "type": "MULTI",
  "definition": {
    "variables": {
      "score": 0,
      "price": 0,
      "segment": "new-customer"
    },
    "hidden_fields": ["campaign_id", "account_id"]
  }
}

Variables

variables is an object with up to 100 entries. Each value must be a string or finite number. Onlyform adds score: 0 and price: 0 when they are omitted, and your supplied values can override those defaults. Use variables as initial values for scoring, pricing, and other form logic. They are returned under definition.variables when you retrieve the form.

Hidden fields

hidden_fields is a list of up to 100 unique names. Matching query parameters on the public form URL provide their values:

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

Hidden-field declarations are returned under definition.hidden_fields. They are logic metadata and do not require visible or hidden question blocks.

Naming rules

Names must match ^[A-Za-z_][A-Za-z0-9_.-]{0,99}$:

Start with a letter or underscore.
Continue with letters, numbers, underscores, hyphens, or periods.
Use at most 100 characters.

Examples: lead_source, campaign.id, and account-id.

The 2026-08-01 contract accepts variables and hidden_fields only during form creation. Sending either section to PATCH /v1/forms/{formId} returns 422 INVALID_DEFINITION_FIELD.

​Variables

​Hidden fields

​Naming rules

Variables

Hidden fields

Naming rules