Internal field identifiers for reports, exports, Workflows, and REST API payloads.

Audience: Admin · Developer

Every Form Builder field has two names:

Label — what field users read on mobile (safe to change anytime).
Field key — stable internal identifier used by reports, Excel exports, Workflows, and the REST API.

Treat keys like database column names.

Where keys appear

Consumer	Uses key for
Form reports	Column headers and filters
Excel export	Header row in `.xlsx`
Workflows	Conditions on `form_submitted` answers
REST API	JSON property names in submission objects
Integrations	Webhook payload fields

If you rename a key after go-live, historical submissions keep the old key; new submissions use the new one. Reports look "empty" for the transition period unless you merge columns manually.

Setting keys in Form Builder

When adding a field:

Set a short, descriptive key in English or snake_case (qty_delivered, defect_code).
Avoid spaces, accents, and special characters—some export tools normalize poorly.
Do not reuse a key for a different semantic meaning later.

Chekku may auto-generate keys from labels on first save—review before publish.

Keys vs. display labels

Label (ES example)	Good key	Poor key
Cantidad entregada	`qty_delivered`	`Cantidad entregada`
Código de falla	`failure_code`	`field_7`

Labels can localize; keys should not.

API access

Authenticated REST clients fetch submissions with nested answer objects keyed by field key. Consult endpoint schemas in Chekku API docs.

Typical pattern:

{
  "visitId": "...",
  "formId": "...",
  "answers": {
    "qty_delivered": 12,
    "failure_code": "F003"
  }
}

List fields store the value column from the Data Source, not necessarily the display label.

Repeatable groups

Repeatable sections prefix or nest keys per instance (items[0].sku). Check API docs for your form version—structure varies by field type.

Migration checklist

If you must change a key:

Freeze form version or publish new form with new key.
Update reports, BI models, and Workflow conditions.
Run parallel exports old vs. new key for one week.
Communicate cutoff date to integration owners.

Prefer never changing keys—update labels instead (Common mistakes).

Tips

Maintain a data dictionary spreadsheet: key, label, type, source list.
Use consistent prefixes per form (audit_, delivery_) when keys might collide in cross-form reports.
Protected Data Source columns still map to keys—mind PII in API responses.

Field keys and API