---
title: "Bulk-import clients from a CSV/Excel spreadsheet"
method: POST
path: "/clients/import"
tags: ["Clients"]
---

# Bulk-import clients from a CSV/Excel spreadsheet

`POST /clients/import`

Imports many clients at once from an uploaded spreadsheet (CSV or Excel). The pipeline auto-detects the file's structure (any language, any delimiter, any leading preamble), then uses Claude to map each row onto the client data model (name, email, address fields, etc.). Rows with no usable name and rows the model flags as non-client are skipped, and duplicates are skipped by matching name or email against the user's existing clients (and earlier rows in the same file). Surviving clients are written in batches. No fields outside the client model are ever created.

## Response `201`

Spreadsheet processed; returns a summary of how rows were classified and how many were imported.

## Other responses

- `400` — Invalid multipart request, empty file, or unparseable spreadsheet
- `401` — Unauthorized
- `500` — Internal Server Error
- `502` — Firestore batch write failed

---

[API](https://skmtc.dev/vocal/apis/magic-heidi-invoicing-software-api.md) · [All operations](https://skmtc.dev/vocal/apis/magic-heidi-invoicing-software-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vocal/magic-heidi-invoicing-software-api/revisions/591ae048f0a0/schema)