Contact Import with Identity Resolution

Contact Import Wizard

SpeyBooks now supports bulk contact import from CSV files with automatic duplicate detection and identity resolution.

Smart Column Detection

• Auto-detected columns — Upload any contacts CSV and SpeyBooks automatically maps Name, Company, Email, Phone, Address, City, Postcode, Country, VAT Number, Company Number, Contact Type, and Payment Terms. No manual column selection needed.
• Generic domain exclusion — Email addresses from shared providers (Gmail, Outlook, Yahoo, etc.) are not treated as identity signals, preventing false matches between unrelated businesses sharing a common email provider.

Identity Resolution Engine

• Hard key matching — VAT numbers, Companies House registration numbers, and company email domains are used as definitive identity signals. If two records share a VAT number, they are the same entity.
• Soft similarity — When no hard keys exist, name and email similarity are scored against configurable thresholds to detect probable matches.
• Three outcomes — Each imported row is classified as Create (new contact), Merge (update existing), or Conflict (needs human review). The preview screen shows every decision with full evidence before anything is written.
• Idempotent imports — Re-importing the same CSV produces merge outcomes with no data duplication. The system is safe to run repeatedly.

Import Preview

• Stats summary — See contacts in file, new contacts, merges, and conflicts at a glance.
• Evidence trail — Every match decision shows why it was made: which hard key matched, or what the soft similarity score was. Fully auditable.
• Conflict blocking — Imports with unresolved conflicts cannot be confirmed until every ambiguity is resolved.

Identity Graph

• Identity anchors — Each contact is linked to a unique identity anchor that persists across imports. Future imports, invoices, and bank transactions all resolve to the same anchor.
• Hard key registry — VAT numbers, company numbers, and email domains are stored as unique keys per organisation. The same key cannot be claimed by two different contacts.
• Progressive adoption — Existing contacts are linked to identity anchors on first merge, with no migration required.

Bug Fixes

• Fixed API key authentication scope for new import endpoints — keys with contacts access now work correctly with the import wizard.

Known Issues

• Conflict resolution UI not yet available — conflicts must be resolved via the API. Frontend conflict resolution will ship in a follow-up release.
• Import history page not yet linked from the main navigation.