All docs

Stable field IDs

Rename a field without losing its history, exports or integration mappings.

Updated . 3 min read.

Every field in a form or funnel has two identities:

  • a name, the key you see in a submission payload (email, company). You can rename it at any time.
  • a field ID, a short code such as fld_9a41c07be2d3 that is assigned once and never changes, even when the field is renamed, relabelled or translated.

Formspring keeps both. A submission still stores its answers under the field names of the day, so existing integrations that read payload.email keep working. On top of that, each submission remembers which field ID every answer belongs to. That is what lets a renamed field keep its history.

What survives a rename

Say a form collected email for a month and you then rename the field to work_email.

Where What you get
CSV and JSON exports One work_email column that holds old and new answers together.
Drop-off analytics The field's reached and completed counts cover all responses, not only the new ones.
Webhooks and the API data_by_id and field_ids keyed by the stable ID, next to the unchanged payload.
Integration field mappings A mapping saved by field ID, by the old name or by the new name keeps sending the right value.
Google Sheets columns A column bound to a field resolves through the same ID.

Responses collected before this feature existed resolve too: Formspring remembers the former names of a renamed field and matches old answers to the field by name.

Reading the ID

Webhook deliveries, REST submission resources and MCP submission tools carry two extra, additive properties:

json
{
  "payload": { "email": "ada@example.com" },
  "field_ids": { "email": "fld_9a41c07be2d3" },
  "data_by_id": { "fld_9a41c07be2d3": "ada@example.com" }
}
  • field_ids maps each answered field's current name to its ID.
  • data_by_id holds the same answers keyed by ID. Use it when your code should not care what the field is called.
  • payload is unchanged and still keyed by the field name that was current when the answer was submitted. Exports are the exception: they present answers under the current name, so a report is consistent across a rename.

If your webhook has a field allow-list (payload_fields), data_by_id follows it. An entry may be a name or a field ID.

Mapping by ID

Wherever you map a field to something else (a CRM property, an Airtable column, a Sheets column, the "email field" of an integration), you can use the field ID instead of the name. Use the ID when you want the mapping to survive renames without touching it. Names keep working; so do names the field used to have.

CSV headers by ID

Exports use field names as column headers. Add columns=id to use the field ID instead, for example when a pipeline joins exports from different months:

text
GET /api/v1/forms/{form}/submissions/export?format=csv&columns=id

Answers that do not belong to a known field keep their stored name as the header.

Funnels

Funnel inputs follow the same rules. Each answered input gets a field ID the first time the funnel is saved in the builder, and renaming the input in the builder keeps it. Renaming an input by replacing the funnel's screens through the API counts as removing one input and adding another, because the API cannot tell the two apart.

What's next