How Merge-by-Matching-Field Actually Works in n8n (With a Worked Example)

Tested by TNT Review — record TNT-TEST-2026-10-05-010, 5 October 2026. The workflow’s structure was validated against n8n’s own schema (0 errors), and we independently simulated its exact matching logic in plain Node against the same two mock data sets — see Verification.

The problem

Data about the same person or record often lives in two different places — a CRM and a support tool, a form and a spreadsheet — and combining them by hand means manually cross-referencing rows. n8n’s Merge node does this automatically, but “combine by matching field” has a few modes that behave differently, and picking the wrong one silently gives you the wrong result.

Expected outcome

By the end of this guide you will understand exactly what “Merge by matching field” does, with a worked example showing precisely which records survive and which get dropped.

Requirements and costs

  • A running n8n instance (free self-hosted, or n8n Cloud’s free trial).
  • Cost: free.

What’s in the template

  1. Source A / Source B (Code nodes, standing in for two real data sources) — each returns a couple of mock records sharing an email field.
  2. Merge by Email (Merge, mode: Combine, Combine By: Matching Fields, field: email) — joins records from both sources where the email matches.

Step-by-step implementation

  1. Download the template from the link below.
  2. In n8n, go to Workflows → Import from File, and choose merge-by-email.json.
  3. Replace the two Code nodes with your real sources — anything that returns items sharing a common field works.
  4. Set fieldsToMatchString on the Merge node to your actual shared field name if it isn’t email.
  5. Choose the right “Output Type”: “Keep Matches” drops anything without a match on both sides; “Enrich Input 1” keeps every Source A record, adding Source B’s fields only where a match exists.

A real example

Source A (a CRM) has a@example.com (Alex) and b@example.com (Bo). Source B (support tickets) has a@example.com (2 open tickets) and c@example.com (1 open ticket). With “Keep Matches,” the only record that survives is:

{ "email": "a@example.com", "name": "Alex", "open_tickets": 2 }

Bo (no matching ticket record) and the ticket for c@example.com (no matching CRM record) are both correctly dropped — “Keep Matches” means exactly that: only records present on both sides.

Verification and troubleshooting

What we actually checked, on 5 October 2026 (record TNT-TEST-2026-10-05-010): the workflow’s 4 nodes and 4 connections were validated against n8n’s own schema (0 errors). Separately, we simulated the exact “combine by field, keep matches” logic in plain Node against the same two mock data sets shown above, and it returned exactly the one matching record with both sources’ fields combined — confirming the expected behaviour by independent calculation, not just by reading n8n’s documentation.

Troubleshooting:

  • You expected more records to survive than did. Check both sources’ values for the matching field are formatted identically — a trailing space or different capitalization in an email address means no match, even though they look the same to a human.
  • You want to keep every Source A record, matched or not. Switch “Output Type” from “Keep Matches” to “Enrich Input 1.”
  • Your two sources have differently-named shared fields (e.g. “email” in one, “contact_email” in the other). Add a Set/Edit Fields node before the Merge to rename one to match the other first.

Free resources

The download contains the ready-to-import workflow and a short setup README.

Download the merge-by-field template (ZIP, 1 KB)

Is there a paid version?

Not yet. This is the complete method. TNT Review has sold nothing to date and has no checkout, so any price we discuss in future should be read as a hypothesis, not an offer.

Leave a comment