CompanyCustomerImports

Import customers into a company

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.
post/v1/companies/{company_id}/customers/imports

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/customers/imports
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

Same key as Idempotency-Key above, but required: the operation writes many rows per call, so a retry without a key would import the same file twice. A missing key answers 400 IDEMPOTENCY_KEY_REQUIRED.

Response

Import completed. Returns the outcome per record, in the same format as the preview. statistics.imported is how many customers were actually created; every other counter classifies the submitted rows.

successboolean required

Example response

{
  "success": true,
  "data": {
    "metadata": {
      "total_customers": 10,
      "is_dry_run": true,
      "processing_time_ms": 450,
      "source_type": "CSV_IMPORT",
      "filename": "clientes_enero.csv",
      "file_size_bytes": 1048576,
      "total_rows": 250
    },
    "customers_validation": [
      {
        "customer": {
          "legal_name": "Empresa Cliente SL",
          "trade_name": "EmpresaCliente",
          "nif": "12345678A",
          "address": {
            "street": "Calle Mayor, 123",
            "number": "123",
            "floor": "2º A",
            "door": "A",
            "postal_code": "28001",
            "city": "Madrid",
            "province": "Madrid",
            "country": "España",
            "country_code": "ES"
          },
          "phone": "+34 612 345 678",
          "billing_emails": [
            "user@example.com"
          ],
          "contact_person": "María García",
          "preferred_payment_method": {
            "method": "BANK_TRANSFER",
            "iban": "ES1234567890123456789012",
            "swift": "ABCDESMMXXX",
            "payment_term_days": 30
          }
        },
        "customer_id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "VALID",
        "errors": [
          {
            "field": "nif",
            "value": "12345678X",
            "message": "NIF not found in AEAT census",
            "code": "CUSTOMER_IDENTIFIER_REQUIRED"
          }
        ],
        "warnings": [
          {
            "field": "email",
            "message": "Email not provided, NIF will be used for invoicing"
          }
        ],
        "row_number": 15
      }
    ],
    "statistics": {
      "total_processed": 10,
      "valid": 6,
      "with_warnings": 2,
      "with_errors": 2,
      "duplicates": 1,
      "invalid_nifs": 1,
      "imported": 8,
      "success_rate": 0.8,
      "importable": 8,
      "not_importable": 2
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.