beel_create_customers_bulk
Create up to 500 customers in a single atomic call. Use dry_run to validate NIFs, duplicates, and formats before persisting.
Instructions
Creates up to 500 customers of this company (NIF) in a single call. The operation is
atomic: if any customer fails validation the whole batch is rejected with 422
BULK_VALIDATION_ERROR and nothing is persisted.
With dry_run=true the batch is only validated — tax identifiers against the AEAT register,
duplicates inside the batch and against the existing customers, field formats — nothing is
written and the answer is 200. With dry_run=false, the default, validation is followed
by creation and the answer is 201. Both modes return the same per-record report, so a dry
run and a real run are read the same way.
Endpoint: POST /v1/companies/{company_id}/customers/bulk
⚠️ Fiscal guardrails — read before calling:
Why a name that does not match the census makes an invoice unsubmittable. (resource: beel://guardrails/nif-validation)
For the exhaustive rules and worked examples, call beel_docs_search.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| dry_run | No | Validate the batch without persisting it (`true`), or validate and create it (`false`, the default). Either way the batch is atomic. | |
| company_id | Yes | NIF (company) the operation acts on. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A NIF you do not reach answers `403`, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed. | |
| idempotency_key | No | Optional idempotency key for this operation. Omit it and one is derived from the request itself, which makes a blind retry safe but also collapses a SECOND, deliberately identical operation into the first for 24 hours. Set it — to an order id, or anything unique per intended operation — whenever you mean to create something that may look identical to what you just created. |