Mapping CSV columns to form fields

The Map Fields stage is where you tell GravityImport where each CSV column belongs. Each row in the mapping table is one column from your file, with a preview of its first values so you can see what’s in it before anything is imported.

Automatic mapping #

GravityImport maps columns for you wherever the column name matches the form. The match is case-insensitive and checks:

The field’s label, admin label, and field ID
Individual input labels for multi-input fields, such as the First and Last inputs of a Name field
The combined “Field Label (Input Label)” format, so a column named Name (First) maps straight to the Name field’s First input
Entry properties, such as Entry ID or Source URL

Columns without a match show Select Form Field so you can map them yourself. Clicking Auto-map runs the automatic matching again at any time, which is useful after you change the form or clear a mapping.

Tip: naming your CSV columns to match your field labels means most of your file maps itself. See Naming your field columns.

Mapping a column manually #

Pick the destination from the column’s dropdown. The list shows:

The form’s fields
Entry properties: Entry Notes, Entry ID, Entry Status, Entry Date, Source URL, User ID, User IP, payment details such as Payment Amount and Transaction ID, and more
Add Form Field, which creates a new field without leaving the importer

Mapping a column to Entry ID has a special meaning: GravityImport updates the existing entries with those IDs instead of creating new ones. See Updating existing entries with the GravityImport plugin.

Adding a form field during import #

No matching field on the form yet? Choose Add Form Field from the dropdown. A dialog opens with the Field Label pre-filled from the column name and a Field Type dropdown, set to Single Line Text by default. Pick the type that suits the data, then click Add Form Field. The new field is added to the form and the column is mapped to it.

The Add Form Field dialog over the dimmed mapping table, with the Field Label pre-filled as "Company", a Field Type dropdown set to Single Line Text, and Add Form Field and Cancel buttons.

Skipping a column #

Untick a column’s checkbox to leave it out of the import. The row dims to show it will be ignored. The header checkbox ticks or unticks every column at once.

The Map Fields mapping table with the Ticket Type column's checkbox unticked and its row dimmed, indicating the column will be excluded from the import. The other columns remain ticked.

Fine-tuning a mapping #

A gear icon appears next to columns with extra settings. For a date column, it opens a dialog where you confirm or change the date format, with a live preview of how the first value will be interpreted. Click Update to apply.

The date format dialog over a dimmed mapping table. It reads "We recognized 2026-05-04 as May 04, 2026" with a format dropdown set to YYYY-MM-DD, a live preview showing "2026-05-04 → May 04, 2026", and Update and Cancel buttons.

Validation before the import runs #

GravityImport checks the preview values as you map. Columns with invalid values are flagged in the table, and a Validation Error Found panel below the mapping lists each problem with a sample failing value and the number of affected rows. Fix the file and upload it again, untick the problem column, or tick Advanced: Continue with errors to proceed anyway. Rows that fail validation are rejected during the import.

The Map Fields stage showing the Amount Paid column flagged with a warning icon. Below the mapping table, a red Validation Error Found banner sits above an Invalid Number Value card reading "Number fields only accept numeric values" and a table listing the column Amount Paid, the sample failing value "free", and 1 of 10 affected preview rows. An Advanced: Continue with errors checkbox appears below, and the Continue With Import button is disabled.

Saving your mapping for reuse #

Running the same import regularly? Download Import Profile, on the Import Complete screen at the end of an import, saves that import’s mapping as a file. On a future import, Load Import Profile applies the whole mapping in one step instead of re-mapping by hand.

Continue with the import #

When the mapping looks right, click Continue With Import to move on to the Configure stage. You can return here later: the Configure and results screens both offer a Change Field Mapping link.