# Salesforce Data Loader: Setup, Upserts and Verified Import Results

Salesforce Data Loader is a client for importing, updating and exporting Salesforce records in bulk. Start with the correct operation, a stable matching key and a small sample before loading a full file. A completed job is only the beginning of validation: reconcile successful and rejected rows, inspect the resulting records and preserve enough before-state evidence to repair an incorrect change.

Canonical URL: https://www.martechdevs.com/blog/salesforce-data-loader

By [Jafrin Akter Alo](https://www.martechdevs.com/authors/jafrin-akter-alo)

Data Engineer and Co-founder at [Martechdevs](https://www.martechdevs.com) and [Growth and Analytics Partners](https://www.growthandanalytics.com)

[LinkedIn](https://linkedin.com/in/jafrinalo)

Last updated: 2026-11-15

Next step: [Salesforce workflow implementation](https://www.martechdevs.com/crm-lifecycle). Define matching, access and accepted customer outcomes.

## Salesforce Data Loader operations

Choose the operation from the intended record change rather than the shape of the spreadsheet.

| Operation | Intended result | Matching requirement | Main validation |
| --- | --- | --- | --- |
| Insert | New records | Required creation fields | No unintended duplicate creation |
| Update | Changes to existing records | Salesforce record IDs | Intended records and fields changed |
| Upsert | Update matches and create unmatched records | Selected external ID or Salesforce ID | Correct match, creation and rejection counts |
| Export | Selected existing records | Object, fields and query scope | Complete intended population |
| Export All | Broader export including soft-deleted records | Explicit broader population | Deleted records distinguished |
| Delete or Hard Delete | Removal of selected records | Correct record IDs | Separately approved removal scope |

Sources: [Data Loader overview](https://developer.salesforce.com/tools/data-loader), [operation definitions](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/loader-operations.html) and [import wizard behavior](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/inserting-updating-or-deleting-data.html).

This guide concerns Salesforce's desktop Data Loader, not a similarly named third-party service or MuleSoft's separate Dataloader offering. The desktop application provides a user interface on supported Windows and Mac systems, while its documented batch command-line mode is supported on Windows. [Salesforce Data Loader](https://developer.salesforce.com/tools/data-loader).

At Martechdevs, [CRM and lifecycle implementation](https://www.martechdevs.com/crm-lifecycle) treats a data load as a controlled customer-process change. We define the matching rule, field ownership, expected result and recovery path before running the wider operation. That makes an import reviewable by the team that will maintain the resulting records.

## Download and environment prerequisites

Download the current release through the [official Data Loader page](https://developer.salesforce.com/tools/data-loader), which directs users to the supported release. Check the release notes for the operating system, processor and Java runtime that apply to the version being installed.

The [version 67.0.0 release notes](https://github.com/forcedotcom/dataloader/releases/tag/v67.0.0) specify Java Runtime 17 or later and list supported Windows and macOS versions and architectures. Use the requirements for your actual release rather than assuming an old installation guide applies to every version. The same release also documents a specific issue with real-time event objects containing JSON-type fields.

Confirm the Salesforce access required for the chosen operation. Create, edit and delete permissions differ, and the relevant objects and fields must be available to the authorized user. The [wizard documentation](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/inserting-updating-or-deleting-data.html) lists operation permissions; a successful login alone does not establish that every requested change is permitted.

Use a named working directory for the input, mapping, before-state export and result files. Keep the original input unchanged and create a separate corrected file for a retry. That separation helps explain exactly which values were submitted in each run.

## OAuth connection setup

Salesforce's current [Data Loader configuration guide](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/configuring-the-data-loader.html) directs users to OAuth 2.0. Its [external client app guide](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/loader-eca-oauth-pkce.html) provides the specific setup for version 64.0.2 and later.

Follow the organization's approved client-app process. The documented setup uses an external client app with OAuth, PKCE and the required API and refresh-token scopes. Its callback address uses localhost and a specified port; the app and Data Loader configuration must agree on that port.

1. Obtain or configure the approved external client app for the target org.
2. Confirm the callback, PKCE and OAuth settings against the current guide.
3. Open Data Loader Settings and enter the correct production or sandbox authentication host.
4. Enter the corresponding external client app consumer key in the correct environment field.
5. Leave the consumer-secret fields empty for the documented PKCE configuration.
6. Match the callback port, save the settings and complete the OAuth login.
7. Confirm the target org and user before selecting an operation.

These steps summarize the [current external-client configuration](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/loader-eca-oauth-pkce.html). A sandbox and production org can have different app policies and keys. Keep those configurations explicit instead of changing a server address while assuming all other authorization settings remain equivalent.

## Input preparation and field mapping

A CSV header is only a label until it is mapped to the intended Salesforce field. Confirm API names, required values, data types and the fields the operation is allowed to change. A familiar label such as Customer ID can refer to a Salesforce ID, an external source key or an unrelated business number.

Use Salesforce IDs for a deliberate update to existing records. For an upsert, choose the external ID field or Salesforce ID that defines matching. The [upsert wizard](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/inserting-updating-or-deleting-data.html) lets the user select the matching field and supports related-object external IDs where the relationship configuration permits it.

Do not assume that a customer name is a reliable key. Similar names can belong to different entities, and a renamed company should usually retain its identity. The [CRM property ownership guide](https://www.martechdevs.com/blog/crm-property-ownership) helps define which system owns the key and the values being loaded.

Keep record identifiers as text in spreadsheet tools. The [Salesforce ID guide](https://www.martechdevs.com/blog/salesforce-15-vs-18-character-id) explains the difference between identifier formats, and the [ID converter](https://www.martechdevs.com/tools/salesforce-id-converter) provides local conversion where needed. A correctly formatted ID still needs to belong to the correct record and environment.

## A three-record upsert example

For a controlled sandbox exercise, assume Account has a custom text field named `External_Customer_Key__c`, configured as an External ID and Unique field. This is an example schema prerequisite, not a standard field that every Salesforce org already contains.

Assume an existing Account already has external key `pilot-101`. Prepare the following hypothetical input file.

```csv
External_Customer_Key__c,Name,Phone
pilot-101,CRM Pilot North,2025550101
pilot-102,CRM Pilot South,2025550102
pilot-103,CRM Pilot West,2025550103
```

The intended operation updates the existing North account and creates South and West. The phone values are illustrative test data. Use an approved sandbox sample and confirm any validation rules or automations affecting Account before running the exercise.

| Input key | Initial state | Expected first run | Expected repeat run |
| --- | --- | --- | --- |
| pilot-101 | Existing account | Update the existing record | Update the same record |
| pilot-102 | No matching account | Create one record | Update the created record |
| pilot-103 | No matching account | Create one record | Update the created record |

The first-run expectation is one update and two creations. After the first accepted run, the sample contains three accounts. Repeating the same upsert should still leave three sample accounts under this matching design. That is different from repeating Insert, which requests new records and can encounter duplicate controls or create unwanted additional records.

Check the input for duplicate external keys before loading. A file containing two conflicting rows for the same key does not provide one clear intended final value. Resolve that conflict rather than relying on processing order to decide the customer's state.

## Upsert execution sequence

1. Select Upsert and authenticate to the approved sandbox.
2. Choose Account and the prepared CSV file.
3. Select `External_Customer_Key__c` as the matching field.
4. Map the three input columns to the corresponding Account fields.
5. Review the mapping and any enabled settings that can change behavior.
6. Choose a dedicated result-file directory and run the bounded sample.
7. Read both the success and error outputs.
8. Inspect the resulting accounts and compare them with the expected first-run state.
9. Repeat the sample only after understanding the first result and its side effects.

The [Data Loader wizard guide](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/inserting-updating-or-deleting-data.html) documents object selection, matching and mapping. The sample does not establish that production has identical rules, permissions or automation. Retain those environment-specific prerequisites in the run plan.

## Blank values and explicit clearing

Decide whether an empty input means Leave the existing value or Clear the field. Those are different operations, and the API mode affects how Data Loader handles them.

For SOAP operations, the Insert null values setting can turn blank mapped values into nulls. For Bulk API and Bulk API 2.0, that setting is unavailable and empty values are ignored during updates. Salesforce documents `#N/A` in the CSV as the explicit null marker for those Bulk API modes. [Data Loader settings](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/configuring-the-data-loader.html).

Test a field with an existing value before applying a clearing rule to a whole file. Also check whether downstream workflows react to the cleared value. A technically successful null update can still violate the intended customer process if another integration immediately writes an older value back.

Record assignment-rule settings for Lead or Case loads. Salesforce documents that a selected assignment rule can override Owner values from the CSV. [Assignment-rule setting](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/configuring-the-data-loader.html). An unexpected owner therefore needs a settings investigation as well as a mapping check.

## Result files and partial success

Data Loader's [output-file guide](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/reviewing-output-files.html) describes success and error CSV files. The success output includes loaded records and generated IDs; the error output identifies rejected records and the reason. Export status-file generation has a separate setting and is not enabled by default for success files.

Suppose a hypothetical import submits 250 rows and returns 238 successes plus twelve errors. The row reconciliation is 238 + 12 = 250. The job has accounted for every submitted row, but twelve intended changes still need a decision.

Correct the rejected rows and retry that bounded set after understanding the cause. Re-running the entire original input can repeat successful work and related automation. The appropriate recovery depends on the operation and matching rule, not merely on whether the first run displayed an error count.

Batch mode has another important boundary. The [exit-code reference](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/loader-operations.html) states that exit code zero can occur with failed rows when `process.batchMode.exitWithErrorOnFailedRows` remains false, its default. For an automated process that must detect partial failure, configure the intended behavior and inspect row-level evidence.

```properties
process.batchMode.exitWithErrorOnFailedRows=true
```

Under that documented setting, a completed operation with rejected rows can return exit code four. This is a batch-mode configuration detail, not a substitute for reading the error file and verifying the business outcome. Keep the Windows-only command-line support boundary in the automation design.

## Export, deletion and recovery boundaries

Export and Export All have different populations. The [operation reference](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/loader-operations.html) distinguishes normal extraction from extraction including soft-deleted records. Keep that choice with the query when reconciling counts or preparing a before-state file.

Deletion needs a separately reviewed list of identifiers. Salesforce warns that Data Loader deletes records based on IDs in the CSV rather than relying on the selected object as a protective boundary. [Deletion behavior](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/inserting-updating-or-deleting-data.html). Verify the actual IDs and environment before approving a removal operation.

Hard Delete bypasses the Recycle Bin. A before-state CSV is useful evidence, but importing it again does not necessarily restore the original identifiers, relationships or downstream history. Define the recovery limitations before removal rather than presenting every bulk change as easily reversible.

The [Salesforce implementation checklist](https://www.martechdevs.com/blog/salesforce-implementation-checklist) covers wider migration and cutover decisions. For read-only query work around a load, the [Workbench and current-tool guide](https://www.martechdevs.com/blog/salesforce-workbench) explains saved queries and complete result handling.

## Import failure diagnostics

| Symptom | Evidence to inspect | Repair | Repeat check |
| --- | --- | --- | --- |
| Application fails to start | Installed release, Java and architecture | Match the release's requirements | Launch and version confirmation |
| OAuth login fails | Environment host and approved app settings | Correct the specific authorization issue | Same target-org login |
| Existing record becomes a new record | Matching field and source key | Repair identity mapping | Known existing/new sample |
| Required value error | Error row and required fields | Supply a valid approved value | Corrected failed row |
| Owner differs from CSV | Assignment-rule setting and automations | Reconcile ownership rules | Record and next-task ownership |
| Blank field stays unchanged | API mode and null handling | Apply the intended explicit clearing rule | One known populated field |
| Batch process returns zero with errors | Exit setting and error CSV | Configure failure detection | Deliberate rejected-row fixture |

Treat an error message as a starting point for diagnosis. A validation rule can reject a value that looks correctly formatted, and an automation can change a field after the load. Inspect the final record and relevant process evidence before declaring the repair complete.

## Load validation and repair workflow

![A before-state and approved operation lead to configuration and a small load. Row failures or incorrect records return to mapping and access before repeated validation and wider rollout.](https://www.martechdevs.com/assets/blog/salesforce-data-loader.svg)

Diagram connections:

- Approved operation and before-state to Release access and CSV mapping. 
- Release access and CSV mapping to Small representative load. 
- Small representative load to Complete row reconciliation. 
- Complete row reconciliation to Input mapping or execution repair: No. 
- Input mapping or execution repair to Release access and CSV mapping. 
- Complete row reconciliation to Record and downstream checks: Yes. 
- Record and downstream checks to Accepted matching and outcomes. 
- Accepted matching and outcomes to Identity or process repair: No. 
- Identity or process repair to Release access and CSV mapping. 
- Accepted matching and outcomes to Controlled wider load and handover: Yes

Both repair routes return to the configuration and mapping before another sample. A corrected input is not enough if the matching rule or assignment setting still produces the wrong result.

## Salesforce Data Loader checklist

- [ ] Download the current release from the official route.
- [ ] Match the release's operating-system, architecture and Java requirements.
- [ ] Confirm the approved OAuth client and target environment.
- [ ] Choose Insert, Update or Upsert from the intended change.
- [ ] Validate the matching key and remove conflicting duplicate input rows.
- [ ] Preserve the original file, mapping and affected before-state values.
- [ ] Test null behavior, ownership and relevant automation on a small sample.
- [ ] Reconcile submitted rows with successes and errors.
- [ ] Configure automated partial-failure detection where applicable.
- [ ] Verify final records and repeat affected checks after repair.

The [CRM data hygiene audit skill](https://www.martechdevs.com/skills/crm-data-hygiene-audit) helps prepare matching and field-ownership checks. Carry the accepted sample and result-file review into the operating handover so the next load follows the same evidence standard.

## Frequently asked questions

### Is Salesforce Data Loader the same product as every service named Dataloader?

Salesforce's desktop Data Loader is not the same product as every service with a similar name. This guide covers the official desktop client and its documented import, export and batch behavior. Confirm the actual application before applying instructions, especially for authentication, supported operating systems, scheduling and billing, because a hosted or third-party service can have different capabilities and controls.

### Can an upsert prevent duplicates without a stable matching key?

An upsert cannot provide the intended duplicate protection without a stable matching key and a correctly selected matching field. Unmatched rows are candidates for new records, while matched rows update existing records. Validate the source key, destination configuration and repeated-run behavior with known examples before treating Upsert as a general solution to inconsistent customer identity.

### Does an empty CSV cell always clear a Salesforce field?

An empty CSV cell does not always clear a Salesforce field. Data Loader's behavior depends on the API mode and null settings. Salesforce documents explicit null handling for SOAP and a separate `#N/A` marker for Bulk API modes. Test one known populated field under the selected configuration before applying a clearing operation across the wider input file.

### Can a Data Loader batch return success while some rows fail?

A Data Loader batch can return exit code zero while some rows fail when the failed-row exit setting remains at its documented default. Review the success and error files and configure the intended partial-failure behavior for automation. A process exit status alone cannot establish that every requested record change succeeded or that the resulting customer workflow is correct.

### Should the whole CSV be replayed after a partially successful import?

The whole CSV should not be replayed automatically after partial success. Identify the successful and rejected rows, determine the failure cause and prepare the appropriate retry scope. Repeating successful rows can repeat updates or downstream actions. The safe recovery depends on the operation, matching key and business process, so validate the corrected subset before expanding the retry.

## Sources

1. [Salesforce Data Loader overview and download](https://developer.salesforce.com/tools/data-loader)

2. [Data Loader version 67 release requirements](https://github.com/forcedotcom/dataloader/releases/tag/v67.0.0)

3. [Data Loader OAuth external client app setup](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/loader-eca-oauth-pkce.html)

4. [Data Loader configuration and null handling](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/configuring-the-data-loader.html)

5. [Data Loader insert, update and upsert wizard](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/inserting-updating-or-deleting-data.html)

6. [Data Loader result files](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/reviewing-output-files.html)

7. [Data Loader operations and batch exit codes](https://developer.salesforce.com/docs/platform/data-loader-impl/guide/loader-operations.html)
