How to rename csv column headers to match salesforce api field names
- Step 1Look up the Salesforce API Name for each target field — In Setup → Object Manager → (your object) → Fields & Relationships, the Field Name / API Name column is the value imports map to. Standard fields use names like
FirstName,LastName,Email,Phone,MailingStreet. Custom fields end in__c(for exampleLead_Source__c). Note that the label shown on the page layout is not the API name. - Step 2Export or assemble your source CSV — Pull the data from your old system, a spreadsheet, or a form export. Save it as
.csv(the tool also reads.tsvand.txt; PapaParse auto-detects comma vs tab). Make sure the first row is the header row — that is the only row this tool reads to build the rename list. - Step 3Drop the CSV onto the tool above — PapaParse parses the file in your browser. The tool lists every column from the header row with a text box beside it. Leading and trailing spaces in the displayed header are trimmed for readability, but the rename writes exactly what you type.
- Step 4Type the Salesforce API field name next to each column — Enter
FirstNamenext toFirst Name,Emailnext toEmail Address,Lead_Source__cnext toSource. Leave a box blank to keep that column's original header unchanged — handy when only a few columns need renaming. - Step 5Run and download the renamed CSV — The button reads
Rename N headersonce at least one box is filled. The result panel shows Headers renamed and Data rows, plus a 10-row preview. Click Download to save<name>.renamed.csv(a plain comma-delimited CSV — no BOM is added). - Step 6Import into Salesforce and confirm the auto-map — Upload the renamed CSV in Data Import Wizard or Data Loader. With the headers matching API names, the mapping screen should show each column pre-matched. Always spot-check the mapping summary before you commit the import — Data Loader will silently skip columns whose name still doesn't match.
Common label-to-API-name renames for Salesforce import
Source headers people commonly export vs. the Salesforce API Name imports map to. Verify each against your own org's Object Manager — API names differ between standard and custom fields, and custom fields always end in __c.
| Salesforce object | Typical source header | Target API Name | Notes |
|---|---|---|---|
| Contact / Lead | First Name | FirstName | Standard field — no space, PascalCase |
| Contact / Lead | Email Address | Email | Standard field; the bare token, not Email_Address |
| Lead | Company Name | Company | Required on Lead inserts |
| Contact | Mailing City | MailingCity | Address sub-fields are one token: MailingStreet, MailingState, MailingPostalCode |
| Account | Account Name | Name | Account's primary text field is just Name |
| Lead (custom) | Source | Lead_Source__c | Custom field — exact developer name plus __c |
| Any (upsert key) | Record ID | Id | Use the 15- or 18-char Salesforce Id for updates; an external-ID field for upserts ends in __c |
What this tool changes and what it leaves alone
The rename operation rewrites only the header row. Everything below it is the responsibility of a different step.
| Aspect | Behaviour | If you need more |
|---|---|---|
Header row (rows[0]) | Rewritten — each renamed column gets the new name, blanks keep the original | This is the whole job |
| Data rows | Passed through unchanged — no trimming, casing, or reformatting of cell values | Use csv-whitespace-trimmer or csv-cleaner first |
| Column order | Unchanged — rename does not move columns; Data Loader maps by name not position anyway | Use csv-column-reorder |
| Extra columns not on the object | Kept in the file — Salesforce ignores unmapped columns, it doesn't error | Use csv-column-remover to drop them |
| Free-tier limit | Blocks above 2 MB or 500 data rows (result-row check); shows the Pro overlay | Pro raises to 100 MB / 100,000 rows |
Cookbook
Before/after header rows from real Salesforce import prep. Data rows are shown only to prove they pass through unchanged.
Contact import: friendly labels to standard API names
ExampleA spreadsheet of contacts with human-readable headers. Data Loader won't auto-map First Name to FirstName. Rename the four columns; the email and phone data rows are untouched.
Input header: First Name,Last Name,Email Address,Phone Number Aisha,Khan,aisha@example.com,+44 20 7946 0000 Renames typed (by column): First Name -> FirstName Last Name -> LastName Email Address -> Email Phone Number -> Phone Output header: FirstName,LastName,Email,Phone Aisha,Khan,aisha@example.com,+44 20 7946 0000
Lead import with a custom source field
ExampleLeads carry a custom Lead_Source__c field. The source export calls it Source. Standard fields and the custom field are renamed in one pass.
Input header: Name,Company,Source J. Okafor,Acme Ltd,Webinar Renames typed: Name -> LastName Company -> Company (blank — already matches, left as-is) Source -> Lead_Source__c Output header: LastName,Company,Lead_Source__c J. Okafor,Acme Ltd,Webinar
Rename only the columns that are wrong
ExampleMost headers already match the API names; only two are off. Leave the matching boxes blank so the tool keeps them verbatim — no need to retype everything.
Input header: FirstName,LastName,Email Address,Title,Phone No Renames typed (others left blank): Email Address -> Email Phone No -> Phone Output header: FirstName,LastName,Email,Title,Phone → Headers renamed: 2
Two columns sharing a label, mapped to different fields
ExampleAn export has two Phone columns (work and mobile) with the same header. Because the tool renames by column position, you can point each at its own Salesforce field.
Input header: Name,Phone,Phone Lee,020 1234,07700 900 Renames typed (by column position): Name -> LastName column 2 Phone -> Phone column 3 Phone -> MobilePhone Output header: LastName,Phone,MobilePhone Lee,020 1234,07700 900
Add the Id column for an update instead of an insert
ExampleTo update existing records, Data Loader matches on Id. Your extract calls it Record ID. Rename it so Data Loader treats the job as an update.
Input header: Record ID,Title 0035g00000ABCDEFGHI,VP Sales Rename typed: Record ID -> Id Output header: Id,Title 0035g00000ABCDEFGHI,VP Sales → In Data Loader, choose 'Update' and map Id as the match key.
Errors and edge cases
Real errors and silent failures sourced from each platform's own documentation. Match the wording to the row, fix what the row says to fix.
Renamed to the label instead of the API Name
Data Loader skips columnIf you rename a column to the field's display label (First Name) rather than its API Name (FirstName), Data Loader treats it as unmapped and silently leaves that field empty on every imported record. Always copy the API Name from Object Manager's Field Name column, not the label on the page layout.
Custom field missing the `__c` suffix
UnmappedCustom fields require the full developer name plus __c (for example Account_Tier__c). Renaming to Account Tier or Account_Tier won't match. Copy the exact API Name — Salesforce auto-generates it from the label by replacing spaces with underscores and appending __c, but always verify rather than guess.
Two columns renamed to the same Salesforce field
Ambiguous mappingThe tool will happily produce two columns both named Email — it renames by position and does not de-duplicate header names. Data Loader's behaviour with duplicate header names is undefined (it typically maps the first and ignores the rest, or errors). Rename one to the correct field and drop the other with csv-column-remover before importing.
Required field (e.g. Lead Company) not present in the file
Insert failsRenaming headers cannot conjure a column that isn't there. Lead inserts require Company and LastName; Contact requires LastName. If the source CSV has no such column, the import errors per row. Add the column upstream (in your spreadsheet) before renaming — this tool only renames existing columns, it does not add them.
Source export uses a tab or semicolon delimiter
SupportedPapaParse auto-detects the delimiter, so a tab-separated .txt or .tsv export is parsed correctly and the header list populates as expected. The download is always written as a comma-delimited CSV (Papa.unparse), which is what Data Import Wizard and Data Loader expect.
Free tier blocks a large contact database
Pro overlayThe free tier checks the result and blocks above 500 data rows or 2 MB, showing the Pro overlay. A full Salesforce migration of tens of thousands of contacts needs Pro (100 MB / 100,000 rows). Alternatively split the file first with a row-slicing tool and rename each chunk, then load them sequentially.
Currency or date columns look 'changed' after import
PreservedThis tool never alters data cells — a +44 phone or a 2026-06-10 date comes out identical to how it went in. If Salesforce stores a date differently, that's Salesforce's locale/format parsing on import, not the rename. The downloaded CSV holds the original string exactly.
No BOM on output, accented names import fine but display oddly elsewhere
ExpectedThe download is UTF-8 without a byte-order mark. Salesforce imports UTF-8 correctly. If you open the same file in Excel-on-Windows afterwards and see José, that's Excel guessing the encoding, not a problem with the import. For Excel-safe round-trips, open via Data → From Text/CSV and pick UTF-8.
Frequently asked questions
What's the difference between a Salesforce field label and its API Name?
The label is the human-readable name shown on page layouts (First Name). The API Name is the programmatic identifier that imports, formulas, and the API use (FirstName for standard fields, Lead_Source__c for custom). Data Import Wizard and Data Loader map columns by API Name, so that's what you rename your headers to. Find it in Setup → Object Manager → (object) → Fields & Relationships, in the Field Name column.
Can I rename headers for custom Salesforce fields?
Yes. Custom field API Names end in __c (double underscore, then c), for example Lead_Source__c or Account_Tier__c. Type the exact string including that suffix. Salesforce derives the API Name from the label by replacing spaces with underscores and appending __c, but always copy the real value from Object Manager rather than reconstructing it by hand.
Does renaming headers change any row data?
No. The tool rewrites only the first (header) row. Every data row below it passes through unchanged — emails, phone numbers, currency, dates, and lead notes are byte-for-byte identical in the output. The result panel even shows a separate Data rows count so you can confirm nothing was dropped.
How do I rename just two columns and leave the rest alone?
Type the new name only in the boxes you want to change, and leave the others blank. A blank box keeps that column's original header. The Headers renamed count in the result reflects only the columns whose name actually changed, so you can verify you touched exactly what you intended.
The tool lets me create two columns with the same name — is that a problem?
It can be. The tool renames by column position and does not prevent duplicate header names, so you could end up with two Email columns. Data Loader's handling of duplicate headers is unreliable. Rename only one of them to the target field and remove the other with csv-column-remover before importing.
Will this set up an update or an upsert in Data Loader?
It just renames headers — the operation type is chosen in Data Loader. For an update, include and rename a Record ID column to Id, then pick 'Update' in Data Loader with Id as the match field. For an upsert on an external ID, rename your key column to the external-ID field's API Name (ending in __c) and pick 'Upsert'.
Does it accept Excel files exported from a spreadsheet?
This tool accepts .csv, .tsv, and .txt. Save your spreadsheet as CSV first (File → Save As → CSV). If you work primarily in Excel, the JAD CSV family includes tools that read XLSX directly — but for header rename, export to CSV and you're set. PapaParse auto-detects comma vs tab delimiters on input.
What's the row and file-size limit?
Free handles files up to 2 MB and up to 500 data rows per job; exceeding either shows the Pro upgrade overlay (the row check runs on the result after renaming). Pro raises the limits to 100 MB and 100,000 rows, which covers most full-org contact and account migrations in a single file.
Does the output include a UTF-8 BOM for Excel?
No — the download is plain UTF-8 with no byte-order mark, written by Papa.unparse. Salesforce imports this correctly. If you need to open the renamed file in Excel-on-Windows with accented characters intact, use Excel's Data → From Text/CSV importer and select UTF-8, rather than double-clicking the file.
Should I remove columns Salesforce doesn't recognise?
It's optional. Salesforce silently ignores columns whose header doesn't map to a field, so extra columns won't break the import. If you'd rather keep the file tidy, run csv-column-remover after renaming to drop the unmapped columns. To reorder for readability, use csv-column-reorder.
Is my CRM data uploaded anywhere?
No. PapaParse runs entirely in your browser; contact emails, lead notes, and account data never reach a JAD server. The only thing recorded server-side is a single usage counter (a file was processed, no content) for signed-in dashboard stats, which you can opt out of in account settings. This matters for CRM data under GDPR/CCPA — the rename adds no exposure surface.
Can I automate this for a recurring Salesforce feed?
Yes. GET /api/v1/tools/csv-header-rename returns the option schema (a renames map of column index to new name). Pair the @jadapps/runner once and POST your CSV to 127.0.0.1:9789/v1/tools/csv-header-rename/run. The runner executes on your machine, so the data never leaves it — useful for a nightly export → rename → Data Loader pipeline.
My headers already match but mapping still fails — what now?
Check for invisible characters: a leading space or a non-breaking space inside the original header. This tool trims leading/trailing spaces in the displayed list, but the underlying file may still carry them — type the clean API Name into the box to overwrite it entirely. If a stray quote or BOM is wrapping the first header, run csv-cleaner first, then rename.
Privacy first
Processing runs locally in your browser with PapaParse. No file is uploaded — only metadata counters are saved for signed-in dashboard stats.