custmatch

Find the records that are the same customer - across your CRM, billing and web sign-ups - group them into households, and write one golden record per customer.

One customer, John Citizen, found in four records from a web sign-up, the app and a store. The golden record at the top takes the best value of each field; "2 value(s)" marks where the records disagree, and a steward can pin the right one. Below it, each line is a link the model made between two records, green for a score of 0.9 or more, with the evidence in the table: "jack" in the app joined through the same email and phone. The dashed line is a bridge - the only link holding app:a003772 to the rest - so it is the one to check if the customer ever looks wrong.

Why

Customer-matching projects stumble on the same problems. Records arrive in different formats, with typos, nicknames and swapped names, and web sign-ups carry little more than a first name and an email. Contact details lie: "noemail@noemail.com" is on a hundred records, a family shares one email, a call centre typed in its own phone number. Spouses, parents and children, twins and two John Smiths look like one person; one weak link chains strangers into a giant customer; nobody can say why two records were merged; a steward's correction is lost on the next run; customer IDs churn downstream; and the data is personal. custmatch is built around those problems: junk and shared contacts are recognised rather than trusted, households are kept apart from people, the match threshold is judged on whole customers so it cannot chain, every link is explained, decisions and IDs survive reruns, and contacts can be matched hashed.

How it works

records ─► clean & normalise ─► profile contacts ─► blocking ─► compare pairs ─► random forest
                                                                                      │
golden records ◄─ households ◄─ customers ◄─ threshold chosen on whole customers ◄────┘

• Clean and normalise names, phones, dates, emails and addresses by country (US, AU, NZ, GB, CA): nicknames, transliteration, Gmail dots, phone formats.
• Profile contacts: each email and phone is personal, a household's, or junk - judged by who shares it, so junk and shared values stop counting as proof.
• Blocking compares only records that share a key (a surname and street, an email...), so a million records make millions of pairs, not half a trillion.
• Compare pairs with name similarity, rarity and graded dates; a random forest learns from a few hundred labelled pairs (active learning picks the useful ones).
• Threshold on whole customers: links are joined into customers, and the threshold is the one whose customers, not pairs, are most accurate - the project's central finding.
• Households group customers by address and shared contacts; a golden record takes the best value of each field.

docs/guide.md explains each step.

Results

_{The two sizes ran on different machines: per record the laptop was about 2 to 2.6 times faster than the cloud machine. On one machine, time per million records rose by about a quarter from 2 to 10 million, most of it in the household and golden-record stage.}

Where it is stronger

• Messy customer data. Placeholder, shared and household contacts are recognised, not trusted, so they stop chaining strangers together: at a million records custmatch scores 97.99 clustered F1 where Splink scores 78.88, and against a CDP's exact-identifier matching it finds 22 to 26 more points of the true matches.
• It keeps going. Accuracy holds as the file grows - 97.99 at a million records, 96.89 at ten million, on one machine. dedupe, about as accurate on 20,134 records (97.75), took 499 seconds and 8.5 GB there against custmatch's 5.4 seconds and 0.35 GB, so a million records was out of reach on the same 16 GB laptop.
• Modest memory. A million records peak at 3.64 GB on a laptop (Splink: 5.96 GB); ten million at 34.0 GB, about 3.4 GB per million, so a 16 GB laptop holds about four million. dedupe needed 8.5 GB for 20,134 records.
• An ensemble for hard files. "matcher_model": "forest_catboost" averages the random forest with CatBoost: +0.41 clustered F1 on average over six datasets, +1.3 on dense genealogy records and +1.8 on sparse sign-ups, never more than 0.03 behind on any dataset, for runs about 30% longer.

Where others win. Splink needs no labels and is faster once its large blocks are skipped (21.6 seconds at a million records), and it can run on Spark across a cluster: its developers matched a billion records that way. custmatch runs on one machine - about 3.4 GB per million records, so tens of millions, not hundreds. On clean records with names and places only, the tools are close.

The report has the full comparison - against Splink, dedupe and a CDP's exact matching, on these files and on each tool's own datasets - with every caveat: the synthetic and Australian files were generated for this project, so their errors are ones the tool was designed around, and it needs good labels. The test suite checks every number against results/*.json.

Quick start

pip install custmatch                 # Python 3.10+ (or from a clone: pip install -e .)
# try it on the bundled demo (1,766 synthetic records, 600 pairs already labelled):
custmatch run examples/demo/config.json --labels examples/demo/labels.csv --out demo_out/

# on your own files: map the columns in a config, label pairs 1 or 0, run
custmatch sample config.json --n 300 --out to_label.csv
custmatch sample config.json --active to_label.csv --n 100 --out more.csv   # the most useful pairs next
custmatch run config.json --labels labels.csv --out results/

config.json maps your files' columns onto custmatch's fields; examples/demo/config.json is a small working example, and all example data is synthetic (examples/README.md). For sparse records - only a first name plus an email or mobile - add "country": "AU" (or your country's code) and label with sample --active: on a sparse Australian test file that took clustered F1 from 54.9 to 81.7 (examples/au/config.json). The run writes clusters.csv (customer and household per record), golden_records.csv, links.csv (every link with its evidence, weakest first), suspect_records.csv and a summary.json with warnings.

The service: custmatch-server

The library runs a batch over files. custmatch-server runs it as a self-hosted service next to your data - one Docker image, one database (Postgres, or SQLite for a trial):

• Source records and their loads kept in the database, every version of every record; files dropped in an inbox loaded and the batch run on a schedule, with health checks and alerts.
• Real-time matching and lookups over HTTP (POST /match, GET /records/...), consistent with the batch run, which reconciles every real-time decision.
• A steward dashboard: the review queue with a breakdown of every score, customers as a network of links, merge and split with previews, pinned golden-record values, decisions that train the next run, approval by a second steward, the model's accuracy and the data's quality
  • every chart with an explanation of how it is calculated and what good looks like.
• API keys with roles, an audit log of every steward action.

docker compose -f server/docker-compose.yml up -d --build db api   # then see server/README.md

The review queue shows the pairs the model was least sure of, closest calls first. Both records here say Jane, but the web sign-up has only an email and a postcode, the app record a surname, a birth date and a mobile, and they share nothing else. The chart explains the 53%: from the base rate, the agreeing first name pushes the score up, and the missing surname and unshared contacts pull it back below the threshold (the yellow line), where the model kept them apart. A steward answers Same person or Different people*; the answer applies at once and teaches the next run.*

How well the model is doing, and where its line is drawn. Each pair of records gets a score from 0 to 1, and the threshold is the score above which two records count as one person. The left chart moves that threshold from 0 to 1: raise it and precision (blue - of the records joined, the share that truly are one person) rises while recall (green - of the true matches, the share found) falls. The dashed line is where custmatch set it, the point where the two balance best (F1, white), judged on whole customers: here an estimated 91.65% precision and 93.51% recall. The right chart counts the pairs at each score. A confident model puts most pairs near 0 (clearly different) or near 1 (clearly the same); the few in the middle are the ones it sends to the review queue.

server/README.md is the operator guide; the report's chapter on the service what it was measured at.

Features

Key: ✅ done and measured · ◐ opt-in · ❌ not built yet.

Matching

Golden records

Operating over time

Trust and privacy

Documentation

Tests

pip install -e '.[test]' && pytest tests/
pip install -e ./server httpx              # the service's tests too

The suite includes a check that every number quoted in the docs still matches results/*.json.

License

Apache 2.0.