Delete several customers of a company
Scopecustomers:writeDeletes the customers listed in ids from this company.
Partial results
- Partial operation: the customers that can be deleted are deleted, and the rest keep
their place in
customers_deletionwith the status that explains why. That is why it answers200with a body instead of204, and why it answers200even when no row could be deleted. HAS_INVOICES: a customer that has invoices cannot be deleted and comes back with that row status.
What deleting means
- Semantics: the same semantics as
DELETE /v1/companies/{company_id}/customers/{customer_id}— the customer is retained internally for tax record-keeping purposes but is no longer exposed by the API, its identifier is released for reuse, and invoices already issued to it keep their own copy of the recipient's details. - Deleting is not deactivating: deleting frees the identifier, so the same NIF can be
registered again, while
PATCHwithactive: falseleaves the customer where it is with its NIF still taken.
Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key
short of the scope an operation needs is answered 403. The scope an operation requires
is shown next to its title, and the full catalogue lives in the Scopes reference.
Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.
In: header
Path Parameters
Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. 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 company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
uuidQuery Parameters
Comma-separated customer IDs
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/customers/bulk?ids=550e8400-e29b-41d4-a716-446655440000%2C550e8400-e29b-41d4-a716-446655440001"{
"success": true,
"data": {
"metadata": {
"total_customers": 10,
"operation": "DELETE_CUSTOMERS",
"is_dry_run": false
},
"customers_deletion": [
{
"index": 0,
"customer_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "DELETED",
"error": {
"code": "CLIENT_HAS_INVOICES",
"message": "A customer with invoices cannot be deleted: its tax record is kept intact. Deactivate it (active: false) to stop using it."
}
}
],
"statistics": {
"total_processed": 10,
"deleted": 7,
"not_found": 1,
"has_invoices": 2,
"has_recurring_invoice": 0,
"errors": 0
},
"deleted_ids": [
"550e8400-e29b-41d4-a716-446655440000"
],
"deactivated_ids": [
"550e8400-e29b-41d4-a716-446655440000"
],
"total": 10,
"successful": 8,
"failed": 2,
"errors": [
{
"customer_id": "550e8400-e29b-41d4-a716-446655440000",
"error": {
"code": "CLIENT_HAS_INVOICES",
"message": "A customer with invoices cannot be deleted: its tax record is kept intact. Deactivate it (active: false) to stop using it."
}
}
]
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again in 60 seconds."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Import customers into a company POST
Imports customers into this company from an uploaded file. - **`source`:** the origin travels in the body. `csv` is a file following the import template, limited to 5 MB and 1,000 records; `holded` is an Excel (`.xlsx`) exported from Holded contacts, limited to 10 MB and 5,000 records. A file over either limit of its `source` is rejected as a whole with `400` (`CSV_FILE_TOO_LARGE` or `TOO_MANY_RECORDS`) and nothing is imported. A file over 12 MB answers `413` (`FILE_TOO_LARGE`) before it is read. A `holded` file that does not open as a workbook answers `422 INVALID_EXCEL_FORMAT`, and one whose columns are not those of a Holded contacts export `422 INVALID_EXCEL_STRUCTURE`. - **This operation writes:** the customers it accepts are created, and a record whose tax identifier already exists in this company is reported as a duplicate rather than created again, so re-importing the same file duplicates nothing. - **`Idempotency-Key`:** required on this operation. - **Rehearsal:** to see what would happen without writing anything, use `POST .../customers/imports/preview`, a separate operation with no effects at all — the import is never governed by a boolean flag.
Create a customer (deprecated) POST
Creates a new customer. - **Deprecated:** use `POST /v1/companies/{company_id}/customers`, which behaves identically. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.