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

List the customers of a company

Scopecustomers:read

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.

GET
/v1/companies/{company_id}/customers

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

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
Value in"legal_name" | "nif" | "email" | "phone" | "city" | "province" | "active" | "created_at"
sort_order?string
Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/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": "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 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"
  }
}

Get a customer of a company GET

Retrieves the complete details of a customer of this company (NIF).

Update a customer of a company partially PATCH

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.