Upload contacts file

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

Upload a contacts CSV file. The UCI engine parses contacts, builds an identity graph using Disjoint Set Union, detects duplicates via signal vector similarity (name 0.40, email 0.35, phone 0.15, postcode 0.10), and returns a merge preview.

Hard keys (VAT number, company registration number, email domain) force identity merges. Soft similarity above threshold triggers conflict review. The preview includes up to 50 outcome groups.

Maximum file size: 5 MB. Only CSV files are accepted.

The response includes a preview array containing the DSU graph outcomes — each entry shows the resolution type (CREATE, MERGE, or CONFLICT), the participating nodes (import rows and/or ledger contacts), and the evidence that linked them. This is everything needed to render the identity resolution UI.

Response

201 CSV parsed and identity resolution preview created. Returns import ID, column mapping, detected headers, conflict stats, and up to 50 preview outcomes.

Show response fields

columnMapping object

Show child attributes

0 string

1 string

2 string

detectedHeaders array<string>

filename string

hasConflicts boolean

importId string

preview array<object>

Show child attributes

evidence array<object>

nodes array<object>

Show child attributes

contactId string nullable

email string

hardKeys array<string>

id string

isLedger boolean

name string

types array<string>

vatNumber string nullable

type string

stats object

Show child attributes

conflicts integer

creates integer

merges integer

skips integer

totalRows integer

validContacts integer

Error codes

400 No file uploaded, non-CSV file, parse error, or no valid contact rows found.

413 File exceeds 5MB limit.

Request POST /v1/contact-imports/upload curl

curl https://api.speybooks.com/v1/contact-imports/upload \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@contacts.csv"

Response 201

{
  "success": true,
  "data": {
    "importId": "dimp_1",
    "filename": "contacts.csv",
    "totalRows": 47,
    "validContacts": 45,
    "stats": {
      "creates": 38,
      "merges": 5,
      "conflicts": 2,
      "skips": 0
    },
    "hasConflicts": true,
    "columnMapping": {
      "0": "name",
      "1": "email",
      "2": "phone"
    },
    "detectedHeaders": [
      "Name",
      "Email",
      "Phone"
    ],
    "preview": [
      {
        "type": "CREATE",
        "nodes": [
          {
            "id": "row_0",
            "isLedger": false,
            "name": "Acme Ltd",
            "email": "accounts@acme.co.uk",
            "vatNumber": null,
            "types": [
              "customer"
            ],
            "hardKeys": [
              "EMAIL_DOMAIN:acme.co.uk"
            ],
            "contactId": null
          }
        ],
        "evidence": []
      },
      {
        "type": "MERGE",
        "nodes": [
          {
            "id": "ledger_12",
            "isLedger": true,
            "name": "Highland Supplies Ltd",
            "email": "info@highland-supplies.com",
            "vatNumber": "GB123456789",
            "types": [
              "supplier"
            ],
            "hardKeys": [
              "VAT:GB123456789"
            ],
            "contactId": "con_12"
          },
          {
            "id": "row_3",
            "isLedger": false,
            "name": "Highland Supplies",
            "email": "info@highland-supplies.com",
            "vatNumber": "GB123456789",
            "types": [
              "supplier"
            ],
            "hardKeys": [
              "VAT:GB123456789"
            ],
            "contactId": null
          }
        ],
        "evidence": [
          {
            "type": "HARD_KEY",
            "confidence": 1,
            "reason": "Shared VAT number: GB123456789"
          }
        ]
      },
      {
        "type": "CONFLICT",
        "reason": "Soft similarity 0.78 below auto-merge threshold",
        "nodes": [
          {
            "id": "row_7",
            "isLedger": false,
            "name": "J Smith Consulting",
            "email": "john@smithconsulting.co.uk",
            "vatNumber": null,
            "types": [
              "customer"
            ],
            "hardKeys": [],
            "contactId": null
          },
          {
            "id": "ledger_25",
            "isLedger": true,
            "name": "John Smith",
            "email": "john@smithconsulting.co.uk",
            "vatNumber": null,
            "types": [
              "customer"
            ],
            "hardKeys": [],
            "contactId": "con_25"
          }
        ],
        "evidence": [
          {
            "type": "SOFT_SIMILARITY",
            "confidence": 0.78,
            "reason": "name: 0.65, email: 1.00, phone: 0.00, postcode: 0.00"
          }
        ]
      }
    ]
  }
}