Upload contacts file

POSThttps://app.speybooks.com/api/v1/contact-imports/upload

Upload a contacts CSV. The engine parses the contacts, groups the import rows and existing ledger contacts that refer to the same entity, detects duplicates by similarity scoring weighted across name, email, phone, and postcode, and returns a merge preview.

A hard key (VAT number, company registration number, or a non-generic email domain) forces an identity merge. Generic email domains (for example gmail.com) are excluded and never form a hard key. A soft similarity above the review threshold raises a conflict for the user to resolve. The preview includes up to 50 outcome groups.

Maximum file size: 5 MB. CSV only.

The response includes a preview array of resolution outcomes. Each entry shows its type (CREATE, MERGE, or CONFLICT), the participating nodes (import rows and existing ledger contacts), and the evidence that linked them. This is everything needed to render the identity resolution UI.

Error responses:

  • 400: no file uploaded, a non-CSV file, a parse error, or no valid contact rows found
  • 413: the file exceeds 5 MB

Response

201CSV parsed and identity resolution preview created. Returns import ID, column mapping, detected headers, conflict stats, and up to 50 preview outcomes.
Show response fields
columnMappingobject
Show child attributes
0string
1string
2string
detectedHeadersarray<string>
filenamestring
hasConflictsboolean
importIdstring
previewarray<object>
Show child attributes
evidencearray<object>
nodesarray<object>
Show child attributes
contactIdstringnullable
emailstring
hardKeysarray<string>
idstring
isLedgerboolean
namestring
typesarray<string>
vatNumberstringnullable
typestring
statsobject
Show child attributes
conflictsinteger
createsinteger
mergesinteger
skipsinteger
totalRowsinteger
validContactsinteger

Error codes

400No file uploaded, non-CSV file, parse error, or no valid contact rows found.
413File exceeds 5MB limit.