Customers

List customers

Returns a paginated list of customers with optional filters

GET
/v1/customers

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

In: header

Query Parameters

page?integer

Page number (starts at 1)

Default1
Range1 <= value
limit?integer

Number of items per page

Default20
Range1 <= value <= 100
active?boolean

Filter by active/inactive status

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

Field to sort by (eg. legal_name, nif, created_at)

sort_order?string

Sort order direction

Default"asc"
Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

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": "B12345678",
        "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": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "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"
  }
}

Import contacts from Holded Excel POST

Imports multiple customers from an Excel file exported from Holded. **Key features**: - **Specific parsing**: Reads exact structure of Holded contacts Excel (29 columns) - **Automatic mapping**: Converts Holded contacts to Customer entities automatically - **Full validation**: Validates NIFs, addresses and required data - **Preview mode**: Allows viewing parsed data before importing **Recommended flow**: 1. **Initial upload**: Call with `preview=true` to get preview 2. **Display data**: Frontend shows parsed Holded contacts 3. **Final import**: Call with `preview=false` to import definitively **Expected Excel structure** (contacts exported from Holded): - Sheet: "Holded" - Rows to skip: 2 (header + empty) - Headers in row 2: Created, Name, ID, Email, Phone, Mobile, etc. (29 columns) - Footer: "Report created automatically with Holded..." **Security limits**: - Max size: 10MB - Max 5,000 records per file - Rate limiting: 5 imports per hour **Automatic Holded → Customer mapping**: - Name → legal_name - ID → identifier (NIF/CIF) - Email → email - Phone/Mobile → phone (prioritizes mobile) - Full address → address - Tags → notes

Update customer PUT

Updates an existing customer