Form elements

A template's elements array is a registry of everything on the form. Elements with a fieldId collect data; the rest are layout.

{
  "id": "el_1",
  "type": "DYNAMIC_FIELD",
  "fieldId": "subject_name",
  "label": "Subject name",
  "dataType": "TEXT",
  "required": true,
  "x": 0, "y": 0, "width": 0, "height": 0
}

Element types

type	Collects data	Purpose
STATIC_TEXT	No	Fixed text on the document, in content
DYNAMIC_FIELD	Yes	A value the applicant supplies
CHECKBOX	Yes	A boolean
DATE	Yes	A date
SIGNATURE	Yes	A signature block

Data types

dataType refines what a DYNAMIC_FIELD holds and what a client should render:

dataType	Value in form_data
TEXT	A string
TEXTAREA	A string, expected to be long
NUMBER	A number
DATE	YYYY-MM-DD
TIME	HH:MM
CHECKBOX	true or false
SELECT	One of options

Templates authored in the newer canvas editor use the lowercase forms (text, number, date, checkbox, signature, image, dropdown, multiselect). Both appear in the wild, so compare case-insensitively rather than switching on the exact string.

Mapping to form_data

form_data is keyed by fieldId:

{
  "subject_name": "Jordan Rivera",
  "subject_dob": "1994-03-11",
  "consent_given": false,
  "grounds": "Subject presented in acute crisis and meets the statutory criteria."
}

Rules:

• Every element with required: true must be present and non-empty.
• options constrains SELECT and multiselect values.
• defaultValue is a suggestion for a client to prefill. Nothing applies it server-side, so send the value you mean.
• Keys the template does not declare are stored and returned unchanged, but are not rendered on the document.

A missing or malformed value returns 422 validation_failed with param pointing at the field: form_data[subject_dob].

Discovering fields at runtime

Read the template rather than hard-coding a payload:

curl -s "$BASE/templates/$TEMPLATE_ID" -H "x-api-key: $API_KEY" \
  | jq '[.elements[] | select(.fieldId != null)
         | {fieldId, label, dataType, required, options}]'

That list is exactly what an integration needs to build a form, validate input before sending it, or map fields from a records system. Templates change; code that reads them keeps working.

Positioning

x, y, width, and height position an element on templates converted from a fixed document. Templates authored in the canvas editor leave them at zero and use the element list purely as a field registry. Send zeroes unless you are reproducing a fixed form layout.

fontSize and fontFamily similarly apply to positioned templates, and fieldMapping carries a legacy mapping some older templates use.