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

Role in the organizationThis endpoint
ownerAllowed
adminAllowed
memberAllowed

Request body

FieldTypeRequiredDescription
customersarrayyes1 to 200 rows
customers[].namestringyes
customers[].emailstringnoUnique inside the organization
customers[].phonestringno
customers[].notesstringno

Example

bash
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.
json
{
  "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.