List the customers

Returns a paginated list of customers, with optional filters.

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

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

Query Parameters

page?integer

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

Default1

Range1 <= value

limit?integer

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

Default20

Range1 <= value <= 100

active?boolean

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.

search?string

Global search by name, NIF or email

legal_name?string

Filter by legal name (partial search case-insensitive)

nif?string

Filter by NIF (partial search)

email?string

Filter by email (partial search)

phone?string

Filter by phone (partial search)

city?string

Filter by city

province?string

Filter by province

sort_by?string

sort_order?string

Value in"asc" | "desc"

Response Body

application/json

curl -X GET "https://app.beel.es/api/v1/customers"

curl -X GET "https://app.beel.es/api/v1/customers"

Customer list with pagination

{
  "success": true,
  "data": {
    "customers": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "legal_name": "Tech Solutions SL",
        "nif": "B12345674",
        "email": "admin@techsolutions.com",
        "phone": "+34912345678",
        "address": {
          "street": "Calle Mayor",
          "number": "15",
          "postal_code": "28013",
          "city": "Madrid",
          "province": "Madrid",
          "country": "España"
        },
        "active": true,
        "created_at": "2024-06-15T10:30:00Z",
        "updated_at": "2025-01-10T14:00:00Z"
      },
      {
        "id": "789abc12-34de-56f7-8901-234567890abc",
        "legal_name": "María García López",
        "nif": "12345678Z",
        "email": "maria.garcia@email.com",
        "phone": "+34654321987",
        "address": {
          "street": "Avenida de la Constitución",
          "number": "25",
          "floor": "3º",
          "door": "B",
          "postal_code": "41001",
          "city": "Sevilla",
          "province": "Sevilla",
          "country": "España"
        },
        "active": true,
        "created_at": "2024-08-20T09:00:00Z",
        "updated_at": "2024-12-01T11:30:00Z"
      },
      {
        "id": "456def78-90ab-12cd-3456-78ef01234567",
        "legal_name": "Distribuidora Levante SA",
        "nif": "A22222222",
        "email": "contabilidad@distribuidoralevante.es",
        "phone": "+34963456789",
        "address": {
          "street": "Polígono Industrial Norte",
          "number": "7",
          "postal_code": "46007",
          "city": "Valencia",
          "province": "Valencia",
          "country": "España"
        },
        "active": false,
        "created_at": "2024-03-10T16:45:00Z",
        "updated_at": "2024-11-20T08:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "items_per_page": 20,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    }
  },
  "meta": {
    "timestamp": "2025-01-20T12:00:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10: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": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation constraint violation.",
    "details": {
      "limit": "must be greater than or equal to 1"
    }
  },
  "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

Authorization

Query Parameters

Response Body

200application/json

400application/json

401application/json

403application/json

422application/json

429application/json

500application/json

defaultapplication/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json