Customers

List the customers

Returns a paginated list of customers, with optional filters.

  • Deprecated: use GET /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.

get/v1/customers

Request

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

Query parameters

pageinteger

Page number, starting at 1. The response echoes it back as pagination.current_page.

limitinteger

How many items to return per page. The response echoes it back as pagination.items_per_page.

activeboolean

Filter by active/inactive status. Defaults to true, so inactive customers must be requested explicitly with active=false. Deleted customers are never returned by either value.

searchstring

Global search by name, NIF or email

legal_namestring

Filter by legal name (partial search case-insensitive)

nifstring

Filter by NIF (partial search)

emailstring

Filter by email (partial search)

phonestring

Filter by phone (partial search)

citystring

Filter by city

provincestring

Filter by province

sort_by'legal_name' | 'nif' | 'email' | 'phone' | 'city' | 'province' | 'active' | 'created_at'

Customer field the list is ordered by. Ties are broken by customer id, so pages are stable.

  • legal_name: legal name.
  • nif: tax identifier.
  • email: email address.
  • phone: phone number.
  • city: city of the address.
  • province: province of the address.
  • active: whether the customer is active.
  • created_at: creation instant.
Example:legal_name

Field to sort by. Results are always tie-broken by a stable internal key, so paging through the collection never repeats or skips a customer.

sort_order'asc' | 'desc'

Sort direction. Shared vocabulary for every sort_order query param: declared once so the generator emits a real enum and an unknown direction is rejected with 400 instead of being silently ignored.

Example:desc

Sort order direction

Response

Customer list retrieved successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "customers": [
      {
        "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
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 87,
      "items_per_page": 20
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

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