Salesforce Data Loader CSV requirements checklist

A Salesforce import succeeds or fails long before you click Finish in Data Loader.

It succeeds or fails when the CSV is prepared.

That is because a Salesforce Data Loader CSV is not “just a spreadsheet file.” It is a contract between:

• your source system
• the CSV export
• the Data Loader parser
• the Salesforce object model
• and the specific operation you are performing, such as insert, update, or upsert

Most teams only discover that after searching for one of these symptoms:

• Salesforce Data Loader invalid CSV file format
• Salesforce Data Loader UTF-8 error
• Salesforce Data Loader CSV requirements
• Salesforce Data Loader external ID import
• Salesforce Data Loader relationship field CSV
• Salesforce Data Loader blank values not updating
• Salesforce Data Loader date format wrong
• Salesforce Data Loader BOM issue
• Salesforce Bulk API CSV delimiter
• Salesforce Data Loader file works in Excel but not in import

This page is built for those real failures.

Why this topic matters

Salesforce imports are fragile in a very specific way: they often look fine until they hit the exact edge case that the importer cares about.

Examples:

• the file is encoded as UTF-8 with BOM instead of plain UTF-8
• the CSV contains more than one object’s data conceptually, but only one object can be processed cleanly in a batch
• the update file is missing a valid match key
• a relationship column needs an external ID expression rather than a raw field name
• blank values are ignored when the operator expected them to clear data
• a spreadsheet round-trip changed delimiters or date shapes
• the header row is “close enough” for a human but not for mapping logic

That is why a real checklist matters more than generic CSV advice.

The first requirement: know which Salesforce import path you are really using

“Salesforce Data Loader” is the user-facing tool, but under the hood the behavior can differ based on:

• operation type
• settings
• Bulk API or Bulk API 2.0 usage
• the object and field types involved

This matters because some CSV rules are general Data Loader rules, while others are specifically documented for Bulk API flows.

For example, Salesforce’s Bulk API CSV preparation docs explicitly say:

• files must be in UTF-8 format
• Bulk API only supports commas as a delimiter

That means one of the first questions for any CSV checklist is: am I preparing a generic Data Loader file, or a file that will be processed through Bulk API behavior where commas are required?

If your team is inconsistent about that answer, imports become inconsistent too.

The second requirement: one object per CSV batch

Salesforce help explicitly notes that a CSV file can contain multiple records and is referred to as a batch, and that all records in a CSV file must be for the same object.

This is one of the most important structural rules in the topic.

It means:

• one batch for Accounts
• another for Contacts
• another for Opportunities
• and so on

Even when your business workflow spans several objects, the import contract is still object-scoped.

This creates one of the most useful search surfaces for the page:

• can one Data Loader CSV contain multiple object types?
• why does my Salesforce import file need one object per batch?
• how do I handle parent-child object imports in separate files?

The right answer is usually:

• split objects into separate files
• load in a defined order
• use IDs or external IDs to relate them

The third requirement: headers matter more than people think

Salesforce Data Loader’s UI and source labels make this very clear: field mapping is about matching Salesforce object fields to your CSV column headers.

That means header quality is not cosmetic. It directly affects how easy and safe the mapping step will be.

A strong header row should be:

• explicit
• stable
• one column per field
• free of duplicate names
• aligned with the field mapping strategy your team expects

Practical rule: header sloppiness creates mapping sloppiness.

That does not always mean headers must literally equal Salesforce API names, because you can still map manually or via a saved map file. But it does mean a production import should avoid vague names like:

• Field1
• Old Email
• New Value
• Ref
• Col A

Better headers reduce human error and support saved mappings.

The fourth requirement: choose your match key before you build the file

This is where many imports go wrong.

A Data Loader CSV for insert is different from a CSV for update or upsert because update-like operations need a reliable way to find the target record.

Salesforce Data Loader source labels make this explicit: for upsert, the object must have either a Salesforce record ID or an external ID.

That leads to a simple checklist question:

Insert

Do you have all required fields to create a new record?

Update

Do you have the Salesforce record ID, or another path supported by your chosen operation?

Upsert

Are you matching on:

• Salesforce Id or
• a real external ID field

If that is undecided, the CSV is not actually ready.

IDs versus external IDs

This deserves its own section because it drives a lot of search traffic and a lot of import failures.

Use Salesforce Id when

• you are updating records already known in Salesforce
• you exported the records first
• you want the most direct match key

Use an external ID when

• the source system has its own durable key
• you want cleaner recurring upserts
• you want to avoid adding Salesforce IDs into every upstream file
• you are relating child records to parent records using non-Salesforce identifiers

Salesforce help explicitly states that you can use an external ID in place of a related record’s Salesforce record ID when processing an upsert to relate records to each other.

That is a big deal because it turns external IDs into more than dedupe helpers. They become relationship keys for import workflows.

Relationship columns are a hidden CSV requirement

One of the most useful Salesforce help snippets here says: you can add a reference to a related object in a CSV file by representing the relationship in a column header.

That is exactly the kind of detail that trips teams up.

A CSV that looks fine from a flat-file perspective may still be wrong for Data Loader if:

• the relationship column is expressed incorrectly
• the wrong field is used for relationship resolution
• the external ID path is not represented the way Salesforce expects

This is why a generic CSV validator is not enough for Salesforce import readiness. You also need Salesforce-aware field design.

The fifth requirement: UTF-8 is not optional

Salesforce help and developer docs are consistent on this: CSV files used in these flows should be UTF-8.

This matters because encoding problems show up as:

• failed imports
• corrupted special characters
• weird parsing behavior
• or invalid CSV file format errors

And there is an especially important detail here:

Salesforce help documents a known issue that newer Data Loader versions, version 28 and later, do not support files encoded using UTF-8 BOM and can raise:

• CSV Error: Invalid CSV file format

That is an unusually high-value detail for the article because it directly answers one of the most annoying real-world failure cases:

• “the file is UTF-8, why is Data Loader still rejecting it?”

The answer can be:

• it is UTF-8 with BOM, and that specific variant is the problem

This is one of the strongest SEO and support angles on the page.

UTF-8 versus UTF-8 BOM: why teams get burned

Spreadsheet tools and editors do not always expose encoding clearly.

A user might say:

• “I saved it as CSV UTF-8” without realizing the tool emitted UTF-8 BOM.

That is why the safest operational habit is:

• create and preserve import files in a text-editor or export path you trust
• verify encoding if Data Loader throws a mysterious CSV format error
• avoid unnecessary spreadsheet resaves on files with special characters

If your org sees many international names, addresses, or picklist values with non-ASCII characters, this matters even more.

The sixth requirement: blank is not always null

This is another Salesforce-specific pain point that many generic CSV pages miss.

Salesforce help says:

• empty field values are ignored when you update records
• to set a field value to null, use a field value of #N/A
• Data Loader also exposes an Insert Null Values setting
• help content also notes that the column must still contain a header

This creates a very important distinction:

Blank in the CSV

may mean “ignore” depending on operation and settings.

Null intent

requires an explicit strategy.

That is why teams often search:

• Salesforce Data Loader blank values not updating
• how to clear a field with Data Loader
• Data Loader insert null values
• Salesforce #N/A null import

A real checklist page should cover that directly because it causes a lot of failed expectations.

The seventh requirement: dates and datetimes are not just strings

Salesforce help has separate guidance around formatting Date and DateTime values in CSV files, and also documents cases where Data Loader can appear to add hours depending on time zone interpretation.

That means date handling is not only a CSV concern. It is also a locale and time zone concern.

Common problems:

• date values imported in the wrong day-month order
• datetime values shifted when viewed in Salesforce
• spreadsheet formatting changing date text before export
• local machine settings influencing what the operator thinks they are importing

Practical rule: export and prepare dates intentionally, and test a tiny sample first.

For date-heavy imports, you want a known-good example row before loading thousands of records.

The eighth requirement: delimiters must match the import path

Teams often assume CSV means:

• “whatever the spreadsheet exported”

That is not safe.

Salesforce developer docs for Bulk API CSV preparation explicitly say:

• Bulk API only supports commas as a delimiter

So if your workflow relies on Bulk API behavior through Data Loader, semicolon-delimited regional exports are a real risk.

This matters because spreadsheet tools in some locales export delimited text using semicolons instead of commas.

That creates a direct checklist item:

• if the import path is Bulk API-related, confirm the file is comma-delimited before you do anything else

A file can look fine in a spreadsheet and still be wrong for the API.

The ninth requirement: required fields still matter after the CSV is structurally valid

A file can be perfect CSV and still be a bad Salesforce import file.

Once structure is trusted, the next layer is object contract:

• required fields
• field lengths
• picklist validity
• lookup expectations
• permissions
• restricted picklists
• duplicate rules
• validation rules

This page is focused on CSV readiness, but it is important to say clearly: CSV validity is necessary, not sufficient.

That is why your checklist should explicitly separate:

1. structural CSV checks
2. Salesforce field and object checks

That separation makes debugging much easier.

The safest practical checklist

Use this sequence before any real import.

1. Confirm the operation

Are you doing:

• insert
• update
• upsert
• delete
• export

The CSV requirements differ depending on the action.

2. Confirm one object per file

Do not mix object types in one batch.

3. Confirm encoding

Use UTF-8. If Data Loader reports invalid CSV format, check for UTF-8 BOM specifically.

4. Confirm delimiter

If the path uses Bulk API rules, ensure comma-delimited CSV.

5. Confirm header row quality

Make sure every column has a clear header and that mapping will be deterministic.

6. Confirm match key strategy

For update or upsert, decide whether you are using:

• Salesforce Id or
• an external ID

7. Confirm relationship columns

If the import references related records, verify the relationship header strategy and the related key strategy.

8. Confirm null handling

If you intend to clear values, do not assume blanks will do it. Review #N/A and Insert Null Values behavior for your flow.

9. Confirm date and datetime formatting

Test a small sample first, especially across time zones or locale-sensitive environments.

10. Run a structural validator before Data Loader

Check:

• consistent row widths
• header stability
• quote handling
• delimiter consistency
• malformed rows
• encoding surprises

That order catches most preventable problems early.

Common mistakes

Mistake 1: using a spreadsheet as the source of truth

It is a helpful editor, not the import contract.

Mistake 2: forgetting that all rows in a batch must belong to one object

This breaks import logic early.

Mistake 3: relying on blanks to clear data

That is not the same as setting a field to null.

Mistake 4: confusing UTF-8 with UTF-8 BOM

This is a direct cause of invalid CSV file format errors in newer Data Loader versions.

Mistake 5: starting an upsert without deciding the match field

The file may be structurally fine but operationally unusable.

Mistake 6: letting locale-specific delimiters or date formats slip in

Regional exports are a common hidden problem.

Mistake 7: testing only with one happy-path row

Salesforce imports should be verified with small realistic samples before large runs.

Which Elysiate tools fit this topic naturally?

The most natural companions for this page are:

• CSV Validator
• CSV Format Checker
• CSV Delimiter Checker
• CSV Header Checker
• CSV Row Checker
• Malformed CSV Checker

These tools fit well because Data Loader failures often start with raw CSV structure long before Salesforce-specific business rules are evaluated.

Why this page can rank broadly

To support broader search coverage, this page is intentionally shaped around several clusters:

Core Data Loader intent

• Salesforce Data Loader CSV requirements
• Salesforce Data Loader CSV format
• Salesforce import CSV checklist

Failure intent

• invalid CSV file format Data Loader
• Data Loader UTF-8 BOM
• Data Loader blank values not updating
• Data Loader wrong date format

Architecture intent

• upsert with external ID Salesforce
• relationship external ID Data Loader
• one object per CSV Data Loader
• Bulk API CSV delimiter Salesforce

That breadth helps one page rank for many real operational questions, not just the literal title.

FAQ

What format does Salesforce Data Loader expect for CSV files?

The safest baseline is UTF-8 CSV with one header row, one object per file, stable headers, and values formatted to match Salesforce field expectations. When Bulk API rules apply, commas are the supported delimiter.

Does Salesforce Data Loader support UTF-8 BOM files?

Salesforce help documents a known issue that newer Data Loader versions, version 28 and later, do not support files encoded using UTF-8 BOM and can return an invalid CSV format error.

Do I need Salesforce record IDs in my CSV?

For many update flows, yes. For upserts, you can match on the Salesforce record ID or on an external ID field. For related records, Salesforce also documents using external IDs to resolve relationships during upsert.

How do I clear a field using Data Loader?

Blank values are often ignored on update unless you use the right null-handling strategy. Salesforce documentation points to #N/A and the Insert Null Values setting as part of that behavior.

Why does my CSV work in Excel but fail in Data Loader?

Because Excel is a viewer and editor, not the import contract. Spreadsheet round-trips can change encoding, delimiter behavior, quoting, date text, and hidden file details such as BOM handling.

What is the safest default?

Treat the CSV like a strict import artifact, not like a casual spreadsheet: verify encoding, delimiter, headers, object scope, match key, relationship columns, null handling, and date formats before loading real data.

Final takeaway

A Salesforce Data Loader CSV succeeds when four things are true at once:

• the file is structurally valid
• the encoding and delimiter match the import path
• the headers and keys support the operation you chose
• and the values match Salesforce’s field expectations

The safest baseline is:

• one object per file
• UTF-8 without avoidable BOM problems
• explicit headers
• explicit ID or external ID strategy
• explicit null strategy
• deliberate date handling
• and structural validation before the import ever reaches Salesforce

That is how a CSV file becomes an actual Data Loader-ready artifact instead of a spreadsheet that merely looks close enough.