Salesforce CSV Import: Column Names, Picklist Values, and Common Errors

Salesforce has two different tools for importing CSV data, and they have different rules: different column names, different date formats, different error behaviour. Using the wrong format for the wrong tool is the most common reason imports fail before a single record is processed.

Getting a CSV into Salesforce cleanly means knowing which tool to use, how columns need to be named, how picklist values are validated, and what the most common error messages actually mean.

Data Import Wizard vs Data Loader: which one you’re using matters

Data Import Wizard is the in-browser tool under Setup → Data Import Wizard. It supports Leads, Contacts, Accounts, Opportunities, and a few other standard objects. It’s capped at 50,000 records per file and uses field labels, the display names you see in the Salesforce UI.

Data Loader is the desktop application. It handles much larger volumes, supports all objects, and uses API field names, the internal names that end in things like LastName, AccountId, or Custom_Field__c.

The two tools are not interchangeable. A CSV prepared for one will not work cleanly with the other.

Column naming: field labels vs API names

Data Import Wizard

Use the display label exactly as it appears in the Salesforce UI. For Leads:

Field label (use this)	API name (don’t use)
`First Name`	`FirstName`
`Last Name`	`LastName`
`Company`	`Company`
`Email`	`Email`
`Lead Source`	`LeadSource`
`Lead Status`	`Status`

The wizard has a mapping step where you can match your column headers to Salesforce fields, so your columns don’t need to match exactly. But the closer they are, the fewer manual matches you’ll need to make on every import.

Data Loader

Use the API field name. These are case-sensitive and must match exactly. Custom fields always end in __c:

API name	Example value
`FirstName`	`Antoine`
`LastName`	`Bielawski`
`Email`	`[email protected]`
`LeadSource`	`Web`
`Custom_Segment__c`	`Enterprise`

To find the API name for a field: Setup → Object Manager → [Object] → Fields & Relationships → look at the “Field Name” column (then add __c for custom fields).

For lookup fields (like Account on a Contact), Data Loader needs the Salesforce record ID, not the account name. For example, AccountId should contain 0015g00000XyZaA, not Acme Corp.

Required fields

Missing a required field causes the import to fail at the row level. Salesforce won’t import that record and logs it as an error.

Leads: Last Name and Company are always required. Contacts: Last Name is required. Account Name is required if you’re not creating a new account per contact. Accounts: Account Name is required.

If these columns are empty in any row, those rows will error. Fix them before importing, don’t rely on Salesforce to skip them gracefully.

Picklist values: exact match required

Salesforce validates picklist fields against the values defined in your org. If the value in your CSV doesn’t match exactly (wrong capitalisation, extra space, slightly different wording), the field is either left blank (for standard picklists) or the row errors out (for restricted picklists).

Common standard picklist fields and their default allowed values:

Lead Status: New, Working, Nurturing, Unqualified, Qualified

Lead Source: Web, Phone Inquiry, Partner Referral, Purchased List, Other

Industry: Agriculture, Apparel, Banking, Biotechnology, Chemicals, Communications, Construction, Consulting, Education, Electronics, Energy, Engineering, Entertainment, Environmental, Finance, Food & Beverage, Government, Healthcare, Hospitality, Insurance, Machinery, Manufacturing, Media, Not For Profit, Recreation, Retail, Shipping, Technology, Telecommunications, Transportation, Utilities, Other

Rating: Hot, Warm, Cold

Your org may have customised these values. Always export the current picklist values from your org (Setup → Object Manager → [Object] → Fields & Relationships → [Picklist Field] → Values) and use those as your canonical list, not the defaults above.

technology, Tech, TECHNOLOGY will all fail against Technology. Normalise before importing.

Date format

Data Import Wizard: expects MM/DD/YYYY. So January 15, 2024 should be 01/15/2024.

Data Loader: accepts ISO 8601 datetime format: 2024-01-15T00:00:00.000Z. For date-only fields, 2024-01-15 also works in most configurations.

If your source data is in European format (DD/MM/YYYY), convert before importing. 05/01/2024 means May 1st to the Import Wizard, not January 5th.

Common error messages and what they mean

REQUIRED_FIELD_MISSING A required field has no value. Check which field is named in the error, usually Last Name or Company on Leads.

INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST The value you’re trying to import doesn’t exist in the picklist definition for that field. Either add the value to the picklist in Setup, or normalise the CSV value to an existing one before importing.

DUPLICATE_VALUE Salesforce’s duplicate rules detected a match with an existing record. This is a policy decision: you can either disable the rule temporarily, update the existing record instead of inserting, or review the matching logic.

FIELD_INTEGRITY_EXCEPTION Usually occurs on dependent picklists, where the child picklist value doesn’t match what’s allowed for the selected parent picklist value. Verify that your value combinations are valid for your picklist dependencies.

UNABLE_TO_LOCK_ROW A concurrent process is locking the record you’re trying to update. This happens when automations (flows, triggers) are running at the same time. Retry the failed rows, or import during low-automation hours.

FIELD_CUSTOM_VALIDATION_EXCEPTION A validation rule in your org is blocking the record. The error message usually includes the validation rule name. You’ll need to either fix the data to satisfy the rule, or temporarily disable the rule and re-enable it after import.

Before you import: the short checklist

Column names match the tool you’re using (labels for Import Wizard, API names for Data Loader)
Last Name and Company are populated on every Lead row
Picklist values checked against current org values, not assumed defaults
Dates in the right format for your tool (MM/DD/YYYY or ISO 8601)
Lookup fields contain Salesforce IDs, not display names (Data Loader only)
Custom field columns end in __c
File is saved as UTF-8

Picklist normalisation is usually the most time-consuming step, especially when you’re importing from an external source that uses free-text for fields like Industry or Lead Source. If you’re doing this regularly, the CSV Normalizer maps every variant to the canonical value and saves the mapping so the next import from the same source is automatic.

Salesforce CSV import: frequently asked questions

What date format does Salesforce use for CSV imports?

The Data Import Wizard expects MM/DD/YYYY (so January 15, 2024 is 01/15/2024). The Data Loader accepts ISO 8601 datetime (2024-01-15T00:00:00.000Z) and date-only YYYY-MM-DD in most configurations. Mixing formats causes silent blank fields, not errors. See how to standardise date formats in a CSV for the conversion steps.

What’s the difference between Salesforce Data Import Wizard and Data Loader?

The Data Import Wizard is browser-based, capped at 50,000 records, supports common standard objects, and uses field labels. Data Loader is a desktop application that handles large volumes and all objects, and uses API field names (case-sensitive). Files prepared for one tool will not work cleanly in the other.

How do I find Salesforce API field names for a CSV import?

Setup → Object Manager → [Object] → Fields & Relationships. The “Field Name” column shows the API name. Custom fields always end in __c. Lookup fields like AccountId need the Salesforce record ID (e.g. 0015g00000XyZaA), not the display name.

How do I fix INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST errors?

The CSV value doesn’t match any value defined in the picklist. Either add the new value to the picklist in Setup, or normalise the source value to one already on the allowed list before importing. See how to standardise picklist values before a CRM import for the full process.

Why are some Salesforce CSV rows importing with blank fields?

Standard (unrestricted) picklists silently blank the field when the value doesn’t match. Date fields blank if the format isn’t what the chosen tool expects. Lookup fields blank if you provided a display name instead of a Salesforce record ID. Always check the import error file for the row-level reason.