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

Update a customer of a company partially

Scopecustomers:write

Updates only the fields present in the body, leaving every other field of the customer as it is.

  • Null vs omitted: a field sent as null is cleared, which is different from omitting it (see PatchCustomerRequest).
  • Only update verb: this is the canonical way to edit a customer. There is no PUT of full replacement under the company, which would clear the fields you omit.
PATCH
/v1/companies/{company_id}/customers/{customer_id}

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
customer_idstring

Customer ID

Formatuuid

Request Body

nif?string
alternative_id?|null
legal_name?string

Customer legal name. Cannot be cleared. Matched against the AEAT census only for individuals; for a company the name is not verified.

Length1 <= length <= 120
trade_name?string|null

Customer trade name. Send null to clear it.

Lengthlength <= 120
address?
phone?string
email?string|null

Email address. Send null to clear it.

Formatemail
Length5 <= length <= 255
website?string|null

Website URL. Send null to clear it.

Match^(https?://.+|)$
Lengthlength <= 255
billing_emails?|null

Additional emails for invoice delivery. Replaced as a whole; send null or [] to remove them all.

contact_person?string|null

Contact person name. Send null to clear it.

Lengthlength <= 200
notes?string|null

Additional notes. Send null to clear it.

preferred_payment_method?
general_discount?number|null

General discount percentage. Send null to clear it.

Range0 <= value <= 100
active?boolean

Whether the customer is active or inactive.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/customers/550e8400-e29b-41d4-a716-446655440000" \  -H "Content-Type: application/json" \  -d '{    "address": {      "street": "Calle Nueva",      "number": "456",      "floor": "5º A",      "postal_code": "28015",      "city": "Madrid",      "province": "Madrid",      "country": "España"    },    "notes": "Cliente se ha mudado a nueva oficina"  }'
{
  "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",
    "email": "user@example.com",
    "website": "string",
    "billing_emails": [
      "user@example.com"
    ],
    "contact_person": "María García",
    "notes": "string",
    "preferred_payment_method": {
      "method": "BANK_TRANSFER",
      "iban": "ES1234567890123456789012",
      "swift": "ABCDESMMXXX",
      "payment_term_days": 30
    },
    "general_discount": 0,
    "active": true,
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "alternative_id": {
      "type": "NIF_IVA",
      "number": "string",
      "country_code": "st"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INVALID_JSON_FORMAT",
    "message": "The field 'due_date' has an invalid date format: '2026-03-04fds'. Expected format: YYYY-MM-DD.",
    "details": {
      "field": "due_date",
      "invalid_value": "2026-03-04fds",
      "expected_format": "YYYY-MM-DD"
    }
  },
  "meta": {
    "timestamp": "2026-03-05T10: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": "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": "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": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "field_name": "Field is required"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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"
  }
}

List the customers of a company GET

Returns a paginated list of the customers of this company (NIF), with optional filters. Only the customers of the company in the path are returned.

Delete a customer of a company DELETE

Deletes a customer of this company (NIF) that has no invoices. - **What deleting means:** the customer is retained internally for tax record-keeping purposes, but is no longer exposed by the API: subsequent requests to it return `404`, and it is never included in the customer list, under any value of the `active` filter. - **Identifier released:** its NIF or alternative identifier is freed, so a new customer may be created with the same identifier. - **Customers with invoices:** they cannot be deleted and the request answers `409` `CLIENT_HAS_INVOICES`. To stop using a customer, update it with `active` set to `false` instead of deleting it.