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>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

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