Customer Import

Create several customers

Creates up to 500 customers in a single call.

  • Deprecated: use POST /v1/companies/{company_id}/customers/bulk, which validates and creates the same way. A dry run still answers 200; an actual creation answers 201 instead of 200.
  • Atomic: if any customer fails validation the whole batch is rejected with 422 BULK_VALIDATION_ERROR and nothing is persisted.
  • dry_run: with true the batch is only validated — tax identifiers against the AEAT register, duplicates inside the batch and against the existing customers, field formats — and nothing is written. With false, the default, validation is followed by creation.
  • Report: both modes return the same per-record report, so a dry run and a real run are read the same way.

Retires on 9 December 2026. See the migration guide for what moved where and what changes when you switch.

post/v1/customers/bulk

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/customers/bulk
  • Auth: HTTP bearer

Query parameters

dry_runboolean

Validate the batch without persisting it (true), or validate and create it (false, the default). Either way the batch is atomic.

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

Example request

{
  "customers": [
    {
      "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"
      ],
      "preferred_payment_method": {
        "method": "BANK_TRANSFER",
        "iban": "ES1234567890123456789012",
        "swift": "ABCDESMMXXX",
        "payment_term_days": 30
      }
    }
  ]
}

Response

Validation completed successfully (dry_run=true). Returns validation results without persisting data using unified format.

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.