NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Customers

Delete several customers of a company

Scopecustomers:write

Deletes the customers listed in ids from this company (NIF).

Partial results

  • Partial operation: the customers that can be deleted are deleted, and the rest keep their place in customers_deletion with the status that explains why. That is why it answers 200 with a body instead of 204, and why it answers 200 even 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 PATCH with active: false leaves the customer where it is with its NIF still taken.
DELETE
/v1/companies/{company_id}/customers/bulk

Authorization

AuthorizationBearer <token>

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

company_idstring

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.

Formatuuid

Query Parameters

idsstring

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,
      "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": "La factura debe tener al menos una línea",
  "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 (NIF) 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 the limit of its `source` answers `413`. - **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 POST

Creates a new customer. - **Deprecated:** use `POST /v1/companies/{company_id}/customers`, which behaves identically.