Contact Imports

Import contacts from CSV using the Universal Contact Index (UCI) engine. The pipeline parses contact rows, builds an identity graph using Disjoint Set Union, detects duplicates via signal vector similarity (Levenshtein ratio with weighted signals), and presents a merge preview before commit.

Contacts flow through four states: upload → resolve (if conflicts) → confirm → completed. The total row conservation law ensures no rows are lost or created during processing: |H| + |V| + |I| + |E| = m.

The import endpoint maps to the contacts scope for API key authorisation. The created_by sentinel uses ?? 0 for API key auth where request.user.id is null.

→ The Contact Imports object

Endpoints

GET https://app.speybooks.com/api/v1/contact-imports/ List contact imports POST https://app.speybooks.com/api/v1/contact-imports/upload Upload contacts file GET https://app.speybooks.com/api/v1/contact-imports/{id} Get contact import details DELETE https://app.speybooks.com/api/v1/contact-imports/{id} Delete a contact import POST https://app.speybooks.com/api/v1/contact-imports/{id}/confirm Confirm contact import POST https://app.speybooks.com/api/v1/contact-imports/{id}/resolve Resolve identity conflicts

Endpoints

GET /v1/contact-imports/ POST /v1/contact-imports/upload GET /v1/contact-imports/{id} DELETE /v1/contact-imports/{id} POST /v1/contact-imports/{id}/confirm POST /v1/contact-imports/{id}/resolve

The Contact Imports Object json

{
  "id": "dimp_1",
  "filename": "xero-contacts-export.csv",
  "totalRows": 47,
  "createdCount": 38,
  "skippedCount": 4,
  "errorCount": 0,
  "status": "completed",
  "engineVersion": "4.0.0",
  "hasConflicts": false
}