# Imports Bulk-load contacts, leads, or companies from CSV/XLSX files. The flow is asynchronous: `store` enqueues a `ProcessImport` job and returns immediately with status `pending`. Poll `status` for progress; fetch the error CSV via `downloadErrors` once finished. ## List imports `GET /api/imports` Returns paginated import jobs owned by the authenticated user, newest first. ### Query parameters - `per_page` (integer) — Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters). ### Example request ```bash curl --request GET \ --get "https://klozzo.com/api/imports?per_page=20" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" ``` ### Response `200` ```json { "data": [ { "id": null, "type": "contacts", "file_name": "adipisci.csv", "status": "pending", "total_rows": 0, "processed_rows": 0, "succeeded_rows": null, "failed_rows": 0, "column_mapping": null, "duplicate_handling": "skip", "errors": null, "error_file_available": false, "progress_percentage": 0, "started_at": null, "finished_at": null, "completed_at": null, "created_at": null, "updated_at": null }, { "id": null, "type": "contacts", "file_name": "fugit.csv", "status": "pending", "total_rows": 0, "processed_rows": 0, "succeeded_rows": null, "failed_rows": 0, "column_mapping": null, "duplicate_handling": "skip", "errors": null, "error_file_available": false, "progress_percentage": 0, "started_at": null, "finished_at": null, "completed_at": null, "created_at": null, "updated_at": null } ], "links": { "first": "/?page=1", "last": "/?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "page": null, "active": false }, { "url": "/?page=1", "label": "1", "page": 1, "active": true }, { "url": null, "label": "Next »", "page": null, "active": false } ], "path": "/", "per_page": 20, "to": 2, "total": 2 } } ``` ## Create an import `POST /api/imports` Creates an import: uploads a CSV/XLSX file of contacts and queues it for processing. Must be sent as `multipart/form-data`. Returns immediately with `status=pending`; poll `GET /api/imports/{id}/status` for progress. ### Body parameters - `type` (string, required) — What to import. One of `contacts`, `leads`, `companies`. - `file` (string, required) — CSV, TXT, XLSX, or XLS. Max 10 MB. - `column_mapping` (object) — Map of `csv_column_name => contact_field_name`. Required for non-conventional headers. - `duplicate_handling` (string) — Action on collision. One of `skip` (default), `update`, `create`. - `location_id` (integer) — Scope the import to a specific location. ### Example request ```bash curl --request POST \ "https://klozzo.com/api/imports" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: multipart/form-data" \ --header "Accept: application/json" \ --form "type=contacts"\ --form "duplicate_handling=skip"\ --form "location_id=1"\ --form "file=@/private/var/folders/yw/tssyhl110hs29p29scc2m0jc0000gn/T/phpi0k13cg52dh7d0QJtkp" ``` ### Response `200` ```json { "data": { "id": null, "type": "contacts", "file_name": "eius.csv", "status": "pending", "total_rows": 0, "processed_rows": 0, "succeeded_rows": null, "failed_rows": 0, "column_mapping": null, "duplicate_handling": "skip", "errors": null, "error_file_available": false, "progress_percentage": 0, "started_at": null, "finished_at": null, "completed_at": null, "created_at": null, "updated_at": null } } ``` ### Response `422` — A file type that is not accepted ```json { "message": "File debe ser un archivo de tipo: csv, txt, xlsx, xls.", "errors": { "file": [ "File debe ser un archivo de tipo: csv, txt, xlsx, xls." ] } } ``` ### Response `422` — Over 10 MB ```json { "message": "File no puede pesar más de 10240 kilobytes.", "errors": { "file": [ "File no puede pesar más de 10240 kilobytes." ] } } ``` ### Response `422` — Nothing to import ```json { "message": "Falta type.", "errors": { "type": [ "Falta type." ] } } ``` ## Fetch an import `GET /api/imports/{id}` Returns one import by id, with its full payload and the original column mapping. For lightweight progress polling, prefer `status` instead. ### Path parameters - `id` (integer, required) — Import ID. ### Example request ```bash curl --request GET \ --get "https://klozzo.com/api/imports/17" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" ``` ### Response `200` ```json { "data": { "id": null, "type": "contacts", "file_name": "adipisci.csv", "status": "pending", "total_rows": 0, "processed_rows": 0, "succeeded_rows": null, "failed_rows": 0, "column_mapping": null, "duplicate_handling": "skip", "errors": null, "error_file_available": false, "progress_percentage": 0, "started_at": null, "finished_at": null, "completed_at": null, "created_at": null, "updated_at": null } } ``` ## Delete an import `DELETE /api/imports/{id}` Removes the import record and original upload from disk. Imported contacts are NOT removed. ### Path parameters - `id` (integer, required) — Import ID. ### Example request ```bash curl --request DELETE \ "https://klozzo.com/api/imports/17" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" ``` ### Response `200` ```json { "message": "Import deleted." } ``` ## Import progress `GET /api/imports/{import_id}/status` Returns the progress of one import in about a kilobyte, meant for polling. Call every 2–5 s until `status` is `completed` or `failed`. ### Path parameters - `import_id` (integer, required) — Import ID. ### Example request ```bash curl --request GET \ --get "https://klozzo.com/api/imports/17/status" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" ``` ### Response `200` ```json { "id": 17, "status": "processing", "total_rows": 1500, "processed_rows": 420, "succeeded_rows": 415, "failed_rows": 5, "progress_percentage": 28, "errors": null, "error_file_available": false, "started_at": "2026-06-05T13:42:00+00:00", "finished_at": null, "completed_at": null } ``` ## Download error CSV `GET /api/imports/{import_id}/errors` Streams a CSV containing the rows that failed validation, with an `error` column appended. Available only when `error_file_available=true` in the status response. ### Path parameters - `import_id` (integer, required) — Import ID. ### Example request ```bash curl --request GET \ --get "https://klozzo.com/api/imports/17/errors" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" ``` ### Response `200` — streamed CSV download ```json "" ``` ### Response `404` — no error file ```json { "message": "No error file" } ```