> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onlyform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables and hidden fields

> Declare initial logic values and URL-provided hidden data when creating a form.

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

```json theme={null}
{
  "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:

```text theme={null}
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`.

<Warning>
  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`.
</Warning>