Import a batch of customers

POST /api/v1/customers/bulk

Creates a batch of customers in one call. Two rules belong to this endpoint and to no other:

1. A batch over the bound refuses the whole request with 413, naming the limit. There is no silent truncation — you would believe the whole file went through and lose its tail.
2. A bad row does not cancel the good ones. Rows are validated one by one; the ones that pass are created, the ones that fail come back with their index and their reason.

Authorization

Request body

Example

curl -X POST -H "x-api-key: $VILLASLOT_API_KEY" -H "content-type: application/json" \
  -d '{"customers":[{"name":"Tomas"},{"name":"Lina","email":"lina@example.com"}]}' \
  "https://villaslot.app/api/v1/customers/bulk"

Response

• 200 OK — the report. summary.failed is not an error: read failed and fix those rows.

{
  "success": true,
  "data": {
    "summary": {"received": 3, "created": 2, "failed": 1},
    "created": [{"id": "8d3e…", "name": "Tomas"}],
    "failed": [{"index": 1, "error": "Erreur de validation : le nom est obligatoire."}]
  }
}

What it refuses

• 413 Payload Too Large — more than 200 rows. Nothing was created; split the batch.
• 422 Unprocessable Entity — customers is missing or is not a list.
• 401 Unauthorized — missing or invalid key, or a key whose bearer left the organization.
• 404 Not Found — unknown id, or an id belonging to another organization. The two are deliberately indistinguishable.
• 429 Too Many Requests — over 120 requests in a minute for this key.

Notes

• The plan ceiling applies row by row: a batch that crosses it creates rows until the limit and reports the rest as failed.
• index is the position in the array you sent, so you can match a failure back to your source file.