Salesforce Lead Conversion Existing Contact Overwrite Rules

Executive Summary

When a Salesforce Lead is converted into an existing Contact, an unchanged Contact value is usually documented platform behavior, not a defect. Salesforce Help states that conversion adds lead information only "into empty fields on the contact and account" ^[1], and the developer reference for the convert call says that when data is merged into existing records, "only empty fields in the target object are overwritten" ^[2]. The Apex guide on the Winter '27 release path (release 264) repeats that existing data, including IDs, is not overwritten ^[3]. A mapped lead field is therefore not a blanket overwrite instruction, a reading that independent guides share ^{[4] [5]}.

The rule has named exceptions. Lead Source can be overwritten on the target Contact only through the opt-in overwriteLeadSource flag in the API and Apex ^[6], and the Lightning flow lists an optional step to update the Lead Source of the existing contact ^[7]. The Do Not Call and Email Opt Out rows of the official field map carry an explicit qualification for leads converted to existing contacts ^[8]. The owner of an existing record is not overwritten ^[2]. Composite addresses are handled component by component, and State/Province and Country transfer only when both are unset on the contact ^[1].

Custom fields never move without a mapping: standard lead fields map automatically, while custom fields need an administrator to define the mapping ^[3], with same-type and length constraints ^[9]. Target-side automation can then change what is observed afterward. Salesforce documents that triggers fire during conversion ^[10], so an immediate read-back and a later read-back should both be recorded before concluding anything.

This report proposes a field-by-field expected-outcome matrix with four sandbox cases (new target with a default, existing blank, existing populated, missing or incompatible mapping), an exceptions group and 15 countable assertions. No conversion experiment was run for this report, so all 15 assertions start as unknown (0 passed, 0 failed, 15 unknown). Only a sandbox run can change that. The scope is business Accounts and Contacts in Lightning Experience at Winter '27 (API version 68.0 ^[11]). Person Accounts, Apex conversion options and managed packages are labeled as separately verified branches.

The recommended order is: record evidence, classify the gap as native behavior, absent mapping, automation overwrite or approved enrichment, and only then consider a reviewed, field-level change. An indiscriminate overwrite Flow is not a recommended default.

Introduction and Background

Admins and RevOps (revenue operations) data owners meet the same symptom repeatedly. A Lead carries a corrected title or a newer phone number, the lead is converted into a Contact that already exists, and the Contact looks the same afterward. The instinct is to suspect a broken mapping and to build a Flow that copies everything across. That instinct skips a prior question: what does the platform promise for this case?

This report answers that question for the search intent "salesforce lead conversion existing contact overwrite" and its close variants. It concerns missing mapped values during conversion, not raising a marketing conversion rate, and it makes no sales-performance claim. The scope is deliberately narrow:

• Objects: business Accounts and Contacts in Lightning Experience.
• Release anchor: Winter '27, API version 68.0. One Salesforce page states general availability as October 12, 2026 ^[12], while a Salesforce developer post describes the final rollout as set for October 9, 2026 ^[11]. The discrepancy is shown here, not resolved. An org receives the release once the window passes for its instance ^[13].
• Separate branches: Person Accounts, Apex conversion options and managed packages are noted where they change the answer, and each needs its own verification.
• Exclusions: consent or legal advice, bulk-conversion products and conversion-rate benchmarks.

Two points about evidence quality shape everything below. First, the behavior described here is longstanding platform behavior documented in current reference pages. Confirm the behavior against the Winter '27 release notes in your org before relying on it. Second, no sandbox experiment was performed for this report. Expected outcomes come from documentation, and actual outcomes are left as unknown for the reader's own org, test date, edition and API version.

The publisher of this report, Cirra, offers an administration interface for Salesforce through the Model Context Protocol (MCP), an open-source standard for connecting AI applications to external systems ^[14]. That context matters for one section only: an AI assistant connected as the user can inventory field definitions, mappings and sanitized before-and-after values, but it cannot infer missing facts, approve its own change or exceed that user's permissions. Everything in the matrix can be done in the native Setup interface first.

The Native Contract: What Conversion Does to Existing Records

New targets versus existing targets

The central distinction is between records that conversion creates and records that conversion updates. For the update case, the developer reference says the account name and other existing data are not overwritten ^[2], and for contacts the name and other existing data are likewise kept ^[6]. A tutorial blog repeats the Help wording that information goes into empty fields ^[15], and a 2012 vendor post describes the same principle as mapping only to Contact fields that are NULL ^[16]. The older post predates Lightning Experience, so it supports the principle, not current screens.

For new records the picture differs. When record types are in use, blank values are replaced with the default picklist values of the new record owner ^[1]. Whether mapped Lead values can replace those defaults on newly created records is not stated in the cited passage, so the fixture treats it as a case to test rather than a documented fact.

Third-party guides agree with the headline rule but vary in precision. One says an existing record's populated fields are not overwritten ^[4]; an older guide says information goes only into blank fields ^[17]; and another advises readers to check whether mapped fields overwrite existing data without stating the rule ^[18]. These pages establish existing coverage, not authority. The Salesforce statements are the contract. Users can also choose to update existing accounts and contacts at all, rather than creating new ones ^[15].

Standard mappings versus configurable custom mappings

Custom lead fields do not move on their own. The administrator specifies how they map to custom account, contact and opportunity fields, a point echoed by a third-party guide ^[19]. Mapping guidelines add constraints that matter for the fixture:

• Types: certain custom lead fields can only be mapped to custom fields of the same data type ^[9]. A DevOps vendor blog states the same idea in general terms ^[20].
• One source per target: each target field can have only one source field ^[19].
• Length: the target field must be of equal or greater length than the lead field ^[9].
• Setting changes: enabling Use Apex Lead Convert may remove previous conversion field mappings, so document mappings before that setting changes ^[21].

Oversized values are a documented, header-dependent case. The SOAP reference says that since API version 15.0 a string too large for the target field makes the call fail with an error ^[2], and that the earlier truncating behavior can be kept on later API versions by sending the AllowFieldTruncationHeader SOAP header. The fixture therefore runs the length case both with and without that header and records which behavior the conversion path in use shows.

The exceptions row: Do Not Call, Email Opt Out, Lead Source and owner

The matrix needs a dedicated exceptions row, because these fields do not follow the generic reading.

• Do Not Call and Email Opt Out: the official field map carries a qualification for leads converted to existing contacts ^[8]. This is platform behavior only. It is not a legal determination, and it is not proof that preferences are synchronized across marketing systems. One vendor blog says Salesforce carries the Email Opt Out value from Lead to Contact during conversion ^[22]; that statement does not address an existing Contact and should not be read against the field-map qualification. Any later update to these fields needs a named business owner and, where applicable, advice from the organization's own compliance function.
• Lead Source: the API and Apex flag overwriteLeadSource defaults to not overwriting, and a third-party guide describes the same flag as the way to overwrite Lead Source on the target Contact ^[4]. In the Lightning flow, another guide calls the Lead Source update an optional step ^[23]. Whether the Lightning step changes a value in a given org is a test case, not an assumption.
• Owner: an ownerId supplied in conversion is not applicable when merging with existing objects. The owner must still be specified for queue-owned leads.

Address components

Composite address handling is where partial updates appear. Salesforce Help says it adds information only to empty individual fields on the contact and account ^[1], and that with State and Country picklists enabled, lead State/Province and Country transfer to an existing contact only when both are unset on the contact. A City value might therefore arrive while a State value does not. The fixture tests address components separately and never treats the address as one field.

Separately verified branches

• Person Accounts: the Apex reference says that converting into a person account uses the person account ID only, and a contactId must not be specified. The Do Not Call and Email Opt Out qualification is described for existing contacts and should not be generalized to person accounts without a separate check.
• Apex conversion options: flags such as overwriteLeadSource apply on the API and Apex paths. Dedupe-bypass flags in the same reference are marked for internal use only, so no documented behavior exists for them.
• Managed packages: no official page read for this report describes managed-package effects on conversion. Treat any installed package that touches Lead, Contact or Account as an unknown until its own documentation and a sandbox run say otherwise.

Field-by-Field Expected-Outcome Matrix

Table 1 below shows the expected outcome by field class and target state. Each cell states the documented expectation and flags where documentation is silent, so a reader can see which cells are evidence and which are hypotheses. Citations appear in the cells where the source states the point directly.

The interpretive point of Table 1 is that the matrix has three kinds of cells. Documented cells can be asserted with a citation. Cells marked unknown are exactly where Flow requests tend to originate, so they are also where an assumption is most expensive. Checkbox semantics are the clearest case: current Salesforce documentation read for this report does not state whether an unchecked value counts as blank on the target, so the fixture adds checkbox and picklist cases only after the text-field cases behave as expected.

Evidence Capture and the Four-Case Sandbox Fixture

What to record before converting

The first step is capturing facts, not fixing anything. Record these items as observed evidence:

1. Lead ID and the Lead field API names under test.
2. Target Account and Contact IDs, as selected in the convert screen, where the user also confirms the Record Owner and Converted Status ^[24].
3. Conversion path: Lightning convert screen, Apex, API or an integration.
4. Conversion timestamp and the converting user, because Salesforce updates the Last Modified Date and Last Modified By on the converted lead.
5. Target field type, length, default value and mapping for each field under test.
6. Accessible automation on Lead, Contact, Account and Opportunity: flows, triggers, validation rules and duplicate rules.
7. Org facts: edition, API version (68.0 for Winter '27) and test date.
8. The expectation: ask what the business expected to change, not just whether conversion succeeded.

The convert path matters. In Lightning, a user must choose the existing record, otherwise a second Contact is created; one guide says the screen offers the existing record when the Company name matches ^[19]. A guide for another tool notes that the Contact must exist before conversion if a lead is to be attached to it ^[23], and a Trailhead unit says that if the contact exists, the user selects it instead of creating one ^[24]. Skipping that step creates a new Contact, which looks like "conversion did not update the Contact" but is a different event. A Trailblazer Community poster from 2017 reported that no field values were copied to the existing Contact on a merge-style conversion ^[25]; the thread has no accepted resolution, so it illustrates the symptom, not a cause.

Which sandbox can host the fixture

The fixture needs real existing Contacts. A Developer sandbox carries configuration only, so the tester creates the Contacts. A Partial Copy sandbox carries a data sample, and a Full sandbox is a replica of production ^[26]. Synthetic records in the fixture should be named so they cannot be mistaken for customers, and no real person's data should be used to test identity-matching behavior. A vendor guide advises testing lead-conversion automation in a sandbox before production ^[27], and Salesforce's own Admin blog says to build new flows in a sandbox, not in production ^[28], as does a Salesforce Ben best-practices guide ^[29].

The four cases

The fixture uses ordinary text fields first. For each case, record the expected value and the actual value in separate columns, and never edit the expectation after seeing the result.

• Case 1, new target with a default: convert with no existing Contact selected. The target text field has a default value, and the lead value is mapped to it. Observe whether the mapped value or the default wins.
• Case 2, existing target blank: select an existing Contact whose mapped field is empty. Expect the lead value to fill it.
• Case 3, existing target populated: select an existing Contact whose mapped field already holds a different value. Expect no change.
• Case 4, missing or incompatible mapping: include a lead field with no mapping, and an over-length value in a mapped field. Expect no copy for the unmapped field, and record whether conversion succeeds, fails or truncates the oversized value in the path used, with and without the AllowFieldTruncationHeader SOAP header where the path allows it.
• Exceptions group: existing Contacts with Do Not Call and Email Opt Out in each state, converted from leads with the opposite state.

The field-contract spreadsheet

Table 2 shows the field-contract structure and counting rule, with synthetic example rows. The "actual" column is empty by design: no conversion was run, so every status is unknown. A full spreadsheet adds columns for target field type, standard or custom, later automation, source URL and approver.

Every assertion has the same counting rule. An assertion passes when the actual value equals the expected value and the tester could read the field. It fails when they differ, and the difference is then classified (native behavior misread, absent mapping, automation overwrite or enrichment request). It is unknown when the field is unreadable because of field-level security, when the case was not run, or when the read-back timing was not recorded. Unknown assertions must never be counted as passes. On the evidence available today the scoreboard is 0 passed, 0 failed, 15 unknown, and the pass rate is undefined, not 100 percent.

Table 2 also shows why field-level security matters. Field history honors the permissions of the current user, and the Admin blog notes that flows can hit roadblocks such as field-level security, permission sets and role-based sharing, so it advises testing as the affected user ^[28]. A tester without read access to a field cannot assert anything about it. Those assertions are unknown by construction, and the right response is a permission fix or a named colleague with access, not a silent pass.

Target-Side Automation, Validation and Duplicates

Immediate versus later read-back

Salesforce states that triggers fire during lead conversion, and the order-of-execution reference places before-save record-triggered flows ahead of before triggers ^[30]. That reference does not mention lead conversion, so it describes a general save sequence, not a verified conversion-specific map. Which Contact or Account automation runs when conversion updates an existing record was not found in any official page read for this research. That is a test, not an assumption.

A record-triggered flow runs on every create or update of its object unless the Start element has entry conditions ^[28]. A post-conversion flow on Lead is typically built as an after-save record-triggered flow ^[31], and the new Contact ID is read from the ConvertedContactId field on the lead ^[31], a field an integration vendor also documents for finding the converted contact ^[32]. Reading the target immediately after conversion and again after a defined interval separates three cases:

• Same at both times, equal to the old value: native behavior or an absent mapping.
• Correct immediately, changed later: a later automation, integration or user edit changed it.
• Wrong immediately: an automation in the conversion transaction changed it, or the mapping is not what was assumed.

Validation, required fields and duplicates

A knowledge article narrows the validation-rule point: rules on Leads, Accounts, Contacts and Opportunities are enforced during conversion only under a specific setting ^[33]. A Salesforce Ben guide likewise advises confirming that Require Validation for Converted Leads is on ^[34]. Because pages differ in emphasis, record the setting's state in the evidence list instead of assuming it.

Duplicate management can change which record receives data. Salesforce Help says possible duplicates are surfaced during conversion, but cross-object duplicate rules are not triggered ^[1]. A conversion that appears to "do nothing" can be a blocked or redirected save, so the result and any error message belong in the evidence record. The related task of merging two existing Contacts is separate and not covered here.

Field history as the comparison tool

Field history can show whether conversion touched a Contact. A Salesforce article says the contactCreatedFromLead or contactUpdatedByLead entry appears in the History related list when a lead is converted into a new or existing contact ^[35]. Tracking is limited to 20 standard and custom fields per object ^[36], so choose the fixture fields deliberately and enable tracking before the test. A change made by automation in a context the viewer cannot read may not be visible to that viewer.

Deciding What You Are Looking At

The admin decision is a classification, made before any change. Four outcomes cover the symptom "mapped Lead value did not appear":

1. Expected native behavior. The target held a value, the rule is empty-fields-only, and nothing is wrong.
2. Absent or incompatible mapping. The field was never mapped, or the type or length rule prevented it.
3. Automation overwrite. The value arrived and then changed; the later change is in a flow, trigger, integration or user edit.
4. Separately approved enrichment. The business wants the newer lead value to win for a named field, which native conversion does not do by itself.

Field-level precedence for enrichment

If outcome 4 is a genuine requirement, it needs an explicit field-level precedence policy before any build. Third-party guides suggest custom automation or code to overwrite existing values ^[4], and one describes a Flow that finds the new Contact ID and updates a status value ^[34]. Those are options, not defaults. A reviewable policy states, per field:

• Source of truth: which system and record is authoritative, and why newer is not automatically better.
• Overwrite rule: never, only when the target is blank, only when approved by the field's owner, or always, with the reason.
• Protected fields: source and communication-preference fields (including Do Not Call, Email Opt Out and Lead Source) are never overwritten because the lead looks newer. Each has a named business owner who decides.
• Identity: the Contact is identified by the explicit selection in the convert screen or by a record ID, never by a guess from a name or email.
• Evidence: the before and after values from the fixture, and a rollback plan in the sandbox.

Picklist mismatch is a common cause of unmapped-looking data, and one guide recommends a Global Picklist, or documentation and org maintenance, to keep lead and contact values aligned ^[34]. One guide says Process Builder can no longer be used to create new automation, which points teams toward Flow ^[23]. In all cases the change goes through normal change control: build in a sandbox, test against the matrix, review, then deploy. A Trailhead unit notes that change sets deploy flows as deactivated, even if the sandbox version was active ^[37], so activation in production is a verified step.

Where AI assistance helps and where it stops

An AI assistant connected through MCP is useful for inventory work. Within what the connected user can see, it can list Lead, Contact and Account field definitions, the conversion mappings, flows and validation rules, and the sanitized before-and-after values captured in the fixture, and it can join them into a draft of Table 2. It cannot:

• infer facts that were not captured, such as a missing checkbox semantic;
• decide a person's identity or merge records on a guess;
• overwrite source or communication-preference fields because a Lead appears newer;
• approve its own change.

The MCP specification says a human should be able to deny tool invocations ^[38], that hosts must obtain explicit user consent before invoking any tool ^[39], and recommends a progressive, least-privilege scope model ^[40]. Salesforce's hosted MCP documentation describes the permission boundary for its servers: every tool call runs with the same permissions as the user who authorized the connection ^[41]. An MCP interface that acts as the connected user inherits that limit, which is why unknown permission-limited fields stay unknown, not passes.

Data Analysis and Evidence

What can be counted

The quantitative material for this topic is small and mostly structural. The documented counts and limits that affect a test plan are:

• Up to 100 LeadConvert objects per API call ^[2], which bounds test batch sizes.
• Up to 20 tracked fields per object for standard field history, as above.
• 15 assertions in the proposed fixture, with a starting scoreboard of 0 passed, 0 failed, 15 unknown.
• 4 cases plus 1 exceptions group, and 9 field classes in Table 1.

Table 3 lists the version and date facts that anchor the report, including two sources that disagree on a Winter '27 date.

The point of Table 3 is traceability. The version and date facts come from Salesforce, and the oversized-value behavior is a documented, header-dependent case that the fixture tests both ways.

How existing guides cover the topic

Two existing guides discuss process, mapping and Flow broadly ^{[34] [23]}, and neither presents a field-by-field expected-outcome matrix for existing targets, which is the narrow gap this report addresses.

Source discrepancies to keep visible

• Merge wording: a Marketo document describes conversion into an existing Contact in an existing Account as working identically to merging ^[43]. That describes that vendor's sync behavior and does not replace the platform rules above. The same document advises checking custom Lead field mappings first ^[43], as does a community reply on a related thread ^[44].

Implications and Future Directions

Make the conversion test a regression check

The fixture is most valuable as a repeatable regression check. Re-run it whenever a mapping changes, a required field is added to Account or Contact, a validation rule is edited, a flow on Lead, Contact or Account is activated, a duplicate rule is changed, or a managed package that touches those objects is upgraded. Flow Tests exist to ensure that existing functionality is not broken when a change is made to a flow ^[45], and one practitioner guide advises covering as much of a flow as possible with tests ^[45]. A vendor guide suggests linking metadata changes to the automation suites they affect, rather than re-running everything each time ^[46]. Each re-run records the org's API version and test date, so a changed result can be tied to a changed input.

Release awareness without overclaiming

Winter '27 includes a large developer theme around headless and MCP tooling, but nothing located for this report ties a lead-conversion rule to it. The honest record entry is "no Winter '27 change to existing-contact conversion was located; release notes not fully reviewed". If a later review of the release notes finds an item, update the matrix and date it. Practice for deployments belongs in a sandbox or separate playground ^[47], and what is documented now should be confirmed in the org, not assumed from an earlier release.

AI-assisted administration

As MCP interfaces mature, an assistant that works as the connected user can shorten the evidence-gathering step without changing who decides. The same discipline applies to any admin interface, including the one published by Cirra: it acts with the user's permissions and approval, it is complementary to Salesforce and its change controls, and it is not a substitute for a sandbox run or a reviewed deployment.

Frequently Asked Questions (FAQs)

Why does Salesforce lead conversion keep old Contact values?

Because conversion into an existing record fills only empty fields, as Salesforce Help and the API reference both state.

Can a Lead convert and overwrite an existing Contact's fields?

Not for general fields. The documented exception is Lead Source via the overwriteLeadSource flag on the API and Apex path, plus the Lightning optional step. Everything else needs a separate, reviewed enrichment change.

Why does a mapped Lead value not appear on the Contact after conversion?

Check in order: the target already held a value; the field is custom and unmapped; the type or length rule blocked the mapping; the field is Do Not Call or Email Opt Out; or a later automation changed it. The fixture distinguishes these.

Does lead conversion merge into an existing Contact?

In Lightning, the user selects the existing contact in the convert screen. For the API, the contactId is required only when updating an existing contact. The result is an update of that Contact under the empty-field rule, not a merge of two Contact records.

How do field mappings work with an existing Account?

The same empty-field rule applies to the Account, and custom mappings still require an administrator definition. Every converted lead must be tied to an Account, new or existing ^[48].

What is the difference between a new and an existing Contact in conversion?

A new Contact is populated from mapped and default values, including default picklist values. An existing Contact keeps its populated fields. In Lightning, the convert screen lets the user select an existing Contact instead of creating a new one.

How does Database.convertLead treat existing Contact fields?

The Apex reference states that the contact name and other existing data are not overwritten, with only LeadSource overwritten when the flag is true. Apex flags are a separately verified branch.

Should a Flow overwrite Contact fields after conversion?

Not by default. A Flow is one option for a defined enrichment requirement, but it needs a field-level precedence policy, a named owner and a sandbox test, and it must never overwrite source or communication-preference fields because the lead is newer.

Conclusion

An unchanged Contact value after Lead conversion is, in most cases, the platform doing what its documentation says: conversion into an existing record fills empty fields and leaves populated ones alone. The exceptions are specific and few: Lead Source through an opt-in flag or optional Lightning step, and Do Not Call and Email Opt Out, which the field map qualifies for existing contacts. Custom fields need explicit, type-compatible mappings, and target-side automation can change the outcome afterward.

The practical sequence is to capture the evidence, run the four-case fixture in a sandbox, classify the gap, and only then decide whether a field needs an approved precedence rule. On the evidence available now, the fixture's scoreboard is 0 passed, 0 failed, 15 unknown, and every unknown is an invitation to test, not a result. A synthetic fixture illustrates the method; it is not a customer benchmark and not a claim about conversion rates. Keep the matrix as a regression check, record the API version and test date each run, and revisit it when the Winter '27 release notes, a mapping or a downstream automation changes.