Rich fields & conditional logic

Beyond the basics (signature, initials, date, text, checkbox), template fields support richer input types and conditional logic — showing or requiring a field based on what the signer entered elsewhere.

Field kinds

kind	Collects	Config
text	free text	—
number	a numeric value (validated numeric on submit)	—
checkbox	a boolean	—
date	a date	—
dropdown	one choice from a list	config.options (required)
radio	one choice from a list	config.options (required)
signature / initials	a signature/initials image	—
file	a signer file attachment	—

dropdown and radio must declare their choices in config.options; creating one without options returns 422 validation_error.

Declaring rich fields

Fields are placed when you author a template (PUT /v1/templates/{id}/fields replaces the set; POST adds one). Add a config object for options, defaults, and conditional rules:

PUT /v1/templates/{id}/fields

curl -X PUT https://api.permissio.us/v1/templates/tpl_x/fields \
-H "Authorization: Bearer $PERMISSIO_KEY" \
-H "Content-Type: application/json" \
-d '{
  "fields": [
    {
      "kind": "dropdown", "label": "Plan", "page": 1, "x": 10, "y": 30, "w": 30, "h": 5,
      "config": { "options": ["Starter", "Growth", "Enterprise"], "default_value": "Growth" }
    },
    {
      "kind": "text", "label": "PO number", "required": true,
      "page": 1, "x": 10, "y": 40, "w": 30, "h": 5,
      "config": { "visible_when": { "field_id": "fld_plan", "op": "eq", "value": "Enterprise" } }
    }
  ]
}'

Conditional logic

A field's config.visible_when shows and requires it only when a controlling field's submitted value matches:

"config": {
  "visible_when": { "field_id": "<controlling field id>", "op": "eq", "value": "Enterprise" }
}

op	Matches when the controlling value…
eq	equals value (a string)
neq	does not equal value (a string)
in	is one of value (an array of strings)

A field hidden by its rule is not required — the signer can complete the envelope without it. This is enforced server-side on submit (the authoritative gate), independent of what any client renders, so a tampered client can't skip a genuinely-required field or be blocked by a hidden one.

What's validated on submit

When a signer submits, Permissio enforces:

• Required fields (that are visible per their rule) must have a value — else 422 invalid_submission with a field_required issue.
• Dropdown / radio values must be one of the field's options — else a field_value_invalid issue.
• Number fields must be numeric — else a field_value_invalid issue.

Rendering

Dropdown, radio, and number values are stamped into the final PDF as text. Signature/initials render as images. File attachments are captured and retained with the envelope's evidence (they are not drawn inline on the flat PDF).

note

The signer-ceremony controls for radio and file, and the conditional show/hide in the signer UI, are rolling out; the field model, validation, and conditional enforcement described here are live and authoritative on the API today (dropdown and number render end-to-end).