Customers

Create a customer

Creates a new customer.

  • Deprecated: use POST /v1/companies/{company_id}/customers, which behaves identically.

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

post/v1/customers

Request

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

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

legal_namestring required

Customer legal name (required).

When you also send a Spanish nif, how it is used depends on the customer: for an individual the AEAT census matches NIF and name together, so a name it does not recognise makes the customer invalid; for a company the name is not verified and only the CIF decides.

trade_namestring nullable

Customer trade name. Optional, but not empty by default: leave it out on creation and it is filled with legal_name, which is what then shows as the recipient's trade name on the invoice PDF. Send it explicitly if the two differ.

The default applies on creation only. A PUT replaces the customer whole, so omitting trade_name there clears it instead of refilling it from legal_name.

nifstring

Spanish Tax ID (9 characters, uppercase only). Structural validation:

  • DNI: 8 digits + 1 letter (e.g., 12345678A)
  • NIE: X/Y/Z + 7 digits + 1 letter (e.g., X1234567A)
  • CIF: Organization letter + 7 digits + 1 control digit/letter (e.g., B12345674)
phonestring

A phone number as this API accepts it: 9 to 20 characters, and only digits, spaces, dashes, parentheses and an optional leading +. Every request that takes a phone number uses this schema.

It is Phone plus the rules enforced on input. A value this schema accepts always satisfies Phone, so anything you send here is something a response can return.

emailstring email nullable

Main contact address (minimum valid email is 5 chars, e.g. a@b.co). Invoice emails go here only when the customer has no billing_emails.

websitestring nullable

Website URL

billing_emailsEmail[] nullable

Addresses that receive the customer's invoice emails. When the send request names no recipients and the invoice has no email_config recipients, invoices go to these addresses, and not to email; email is used only when billing_emails is empty.

contact_personstring nullable

Contact person name (optional)

notesstring nullable

Additional notes about the customer (optional)

general_discountnumber nullable

General discount percentage (optional)

Example request

{
  "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

Customer created successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "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
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

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