Skip to main content

API Design Specifications

REST APIs for orchestrating the import lifecycle.

POST /api/v1/contacts/import​

Accepts multipart/form-data. Response: 202 Accepted

{
  "jobId": "job-123",
  "status": "UPLOADED"
}

GET /api/v1/contacts/import/:jobId/status​

Polls current chunk progress. Response: 200 OK

{
  "status": "PROCESSING",
  "progress": 45,
  "stats": {
    "totalRows": 150000,
    "processedRows": 67500,
    "valid": 67000,
    "errors": 500
  }
}

GET /api/v1/contacts/import/:jobId/preview​

Returns a paginated view of valid data, warnings, and errors. Response: 200 OK

POST /api/v1/contacts/import/:jobId/confirm​

Triggers the final persistence worker to move data from chunks into the Contact table. Response: 202 Accepted

GET /api/v1/contacts/import/:jobId/reports/errors​

Generates a downloadable CSV containing only the failed rows with an appended FailureReason column.