Merge two CSV files on a key

Paste both CSV texts, name the header they share, and receive a predictable left-joined result without setting up a database or writing a temporary script. The response also separates records that failed to match on the left and on the right, making omissions easy to review. Quoted values, repeated keys, header collisions, and common line endings are handled deterministically, so the same input always produces the same structured output.

Prepare two CSV files with a reliable shared key

Start by identifying the column that represents the same thing in both files, such as customer_id, order_number, sku, or email. The header spelling must match the key value you submit exactly, including capitalization and spaces. Every other header may differ. The left CSV is the primary table: every one of its records remains in the joined output, whether a matching right record exists or not. The right CSV contributes additional columns when its key value matches. Use a stable identifier whenever possible. Names and descriptions often change, contain inconsistent spacing, or repeat, while a system identifier is usually safer. The parser understands quoted fields, escaped double quotes, commas inside quoted values, embedded line breaks, CRLF files, and an initial UTF-8 byte-order mark. If both files use a separator other than a comma, provide that one-character delimiter. Both inputs must use the same delimiter. Empty and duplicate column names are rejected because they would make the resulting objects ambiguous. The capability also stops with a clear input error if the requested key header is absent from either CSV, rather than silently returning a misleading table with no matches.

Understand the left join and duplicate-key behavior

For each record in the left CSV, the capability looks up records in the right CSV with exactly the same key text. A single match produces one combined record. No match still produces one joined record: the original left fields are preserved and every contributed right field is an empty string. When the right file contains several records with the same key, the left record expands into one output record for each right-side match. This one-to-many behavior is useful for joining a customer to several subscriptions or a product to several warehouse entries, but it can increase the output row count. Duplicate keys on the left are processed independently and retain their original order. Rows and matches remain in source order, which keeps results deterministic and makes comparisons straightforward. The shared key appears only once in each joined object. If a non-key right header already exists on the left, its output name gains a right_ prefix so neither value is overwritten. Additional prefixes are added if necessary to keep every output header unique. The columns array gives the exact final order and names before you consume joined_rows in another system.

Use unmatched reports to reconcile data safely

A successful join is only part of a reconciliation task. The unmatched_left array contains original left records whose key had no counterpart on the right. These entries still appear in joined_rows because this is a left join, but the separate list lets you route them for correction, enrichment, or review. The unmatched_right array contains original right records that were never used by any left record. They do not appear in the joined table, yet they often reveal stale reference data, unexpected new identifiers, or a file supplied for the wrong reporting period. Counts summarize both source sizes, the expanded joined size, and unmatched totals, making automated quality checks simple. For example, a workflow can reject an import whenever unmatched_left is greater than zero or alert an operator when unmatched_right rises above an expected threshold. Matching is exact and does not trim, normalize case, or reinterpret numbers, so values such as 001, 1, and 1 with a trailing space remain distinct. That conservative rule prevents accidental associations. Normalize keys before calling this capability when your business rules explicitly allow those values to be treated as equivalent. At $0.002 per request through the API, the operation can be inserted into repeatable imports as well as used for one-off investigations.