How to Merge Duplicate Contacts in Velveteen
Updated August 11, 2026
An administrator can merge two contacts from a contact detail page after choosing a different target and entering a reason. Velveteen previews the bounded records first; execution moves eligible source history to the target, preserves the stricter consent outcome, redacts durable source copies, and anonymizes the source contact.
Use merge only when two records represent the same person and you have reviewed the proposed target. The operation is scoped to the active email workspace; it is different from moving a contact relationship between brands. For the wider CRM model, see Email CRM and Consent.
How do I preview a duplicate-contact merge?
- 1
Open the contact detail page
In Dashboard, open CRM and select the contact record you want to treat as the source. The contact detail page exposes the merge controls only to an administrator. - 2
Choose the target contact
In Merge contact, select a different contact under Select target contact. The source and target must both belong to the resolved workspace, and an erased contact cannot be edited. - 3
Enter a reason
Enter a reason with at least three characters. Velveteen records the trimmed reason with the privacy operation; the stored reason is bounded to 500 characters. - 4
Select Preview merge
Choose Preview merge before any contact mutation. The response is a dry run with an operation ID and bounded counts for source and target brands, topics, notes, consent events, lists, tags, timeline records, campaign records, messages, imports, suppressions, automation runs, and scanned payload copies.
What should I check before execution?
Review the target identity and the preview counts. A merge can move source relationships and history to the target, including eligible brand relationships, topic subscriptions, notes, consent events, list and tag memberships, timeline records, campaign records, attributions, platform events, messages, and automation runs. The preview also checks bounded durable copies that may contain the source contact's data.
Heads up
How do I execute the merge?
- 1
Confirm the preview
After the preview is ready, select Execute merge. Velveteen requires the preview's operation ID so execution remains tied to the same workspace, source, and target scope. - 2
Wait for the acknowledgement
A completed operation reports Contact merge completed and identifies the target with mergedInto. The source is then marked erased and its durable copies are redacted or moved according to the operation's bounded write sequence. - 3
Retry only from the recorded state
If execution returns a failed privacy operation, use the operation acknowledgement and dashboard state before trying again. The write sequence is resumable and idempotent, and a completed operation is acknowledged without repeating the merge.
Tip
Frequently asked questions
Who can merge contacts?+
Contact merge is an administrator-only CRM operation. The CRM API requires email-admin access and resolves the selected workspace before reading or changing contact data.
Can I merge contacts from different workspaces?+
No. Both contacts must resolve in the selected workspace. Foreign or cross-workspace source data causes the merge source to be unavailable.
Does a merge broaden consent?+
No. Velveteen combines brand consent with a consent merge rule in which suppression, unsubscribe, and cleaned outcomes are preserved; an unknown or pending source does not make the target subscribed.
What happens to the source contact?+
After the merge writes complete, the source contact is marked erased, its email is replaced with an invalid.local address, and its first name, last name, phone, and custom fields are cleared. The source cannot be restored through this workflow.
What if the preview or execution fails?+
A preview failure is retryable and does not execute the merge. If an execution write fails, Velveteen records a failed privacy operation and returns a failed response; source anonymization occurs after relationship and history work, so a failed write does not silently complete the merge.
Related articles
Email CRM
Manage the canonical contact record, consent evidence, audiences, source history, and privacy controls without mixing account or purchase status with marketing permission.
Reviewing email imports
Run a staging-only CSV dry run, inspect its counts and consent mapping, then approve or cancel the reviewed import.