> ## Documentation Index
> Fetch the complete documentation index at: https://docs.homele.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Customers

> Returns a paginated list of customers with basic information and related data.

**Permission required:** `customer:read`



## OpenAPI

````yaml GET /customers
openapi: 3.1.0
info:
  title: Homele CRM
  description: Read-only REST API for external CRM integrations
  version: 2.0.0
servers:
  - url: https://crm.homele.com/api/v2/crm
security:
  - bearerAuth: []
paths:
  /customers:
    get:
      tags:
        - Customers
      summary: List Customers
      description: >-
        Returns a paginated list of customers with basic information and related
        data.


        **Permission required:** `customer:read`
      operationId: listCustomers
      parameters:
        - name: cursor
          in: query
          required: false
          description: >-
            Cursor for the next or previous page, taken from `meta.next_cursor`
            or `meta.prev_cursor`
          schema:
            type: string
        - name: per_page
          in: query
          required: false
          description: Results per page (max 100)
          schema:
            type: integer
            default: 25
            maximum: 100
        - name: filter[query]
          in: query
          description: Search by customer name
          schema:
            type: string
        - name: filter[lead_status.id][]
          in: query
          description: Filter by lead status ID
          schema:
            type: integer
        - name: filter[owner.id][]
          in: query
          description: Filter by owner ID
          schema:
            type: integer
        - name: filter[lead_source.id][]
          in: query
          description: Filter by lead source ID
          schema:
            type: integer
        - name: filter[priority.id]
          in: query
          description: Filter by priority ID
          schema:
            type: integer
        - name: filter[date_from]
          in: query
          description: Created after date (YYYY-MM-DD)
          schema:
            type: string
            format: date
        - name: filter[date_to]
          in: query
          description: Created before date (YYYY-MM-DD)
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Paginated list of customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerListItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    CustomerListItem:
      type: object
      properties:
        id:
          type: integer
          example: 42
        sequential_number:
          type: integer
          example: 1025
        name:
          type: string
          example: Ahmed Ali
        first_name:
          type: string
          example: Ahmed
        last_name:
          type: string
          nullable: true
          example: Ali
        phone1:
          type: string
          example: '+9647501234567'
        phone2:
          type: string
          nullable: true
        phone3:
          type: string
          nullable: true
        email1:
          type: string
          nullable: true
          example: ahmed@example.com
        address:
          type: string
          nullable: true
          example: Erbil, 60m Street
        budget:
          type: string
          nullable: true
          example: '150000.00'
        budget_currency:
          type: string
          nullable: true
          example: USD
        expected_sale_date:
          type: string
          nullable: true
          format: date
          example: '2026-06-15'
        lead_status:
          $ref: '#/components/schemas/RelatedObject'
        lead_source:
          $ref: '#/components/schemas/RelatedObject'
        owner:
          $ref: '#/components/schemas/RelatedObject'
        priority:
          $ref: '#/components/schemas/RelatedObject'
        country:
          $ref: '#/components/schemas/RelatedObject'
        city:
          $ref: '#/components/schemas/RelatedObject'
        created_at:
          type: string
          format: date-time
          example: '2025-11-20T14:30:00+00:00'
        updated_at:
          type: string
          format: date-time
          example: '2026-02-15T09:45:00+00:00'
        last_activity_at:
          type: string
          nullable: true
          format: date-time
          example: '2026-02-14T16:20:00+00:00'
    PaginationMeta:
      type: object
      properties:
        per_page:
          type: integer
          example: 25
        next_cursor:
          type: string
          nullable: true
          example: eyJsYXN0X2FjdGl2aXR5X2F0IjoiMjAyNi0wMi0yMCIsImlkIjo0NDB9
        prev_cursor:
          type: string
          nullable: true
          example: null
        has_more:
          type: boolean
          example: true
    RelatedObject:
      type: object
      nullable: true
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: New
  responses:
    Unauthenticated:
      description: Missing or invalid token
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Unauthenticated.
    Forbidden:
      description: Token lacks required permission
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Insufficient permissions.
    RateLimited:
      description: Rate limit exceeded (60 requests/minute)
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Too Many Attempts.
              retry_after:
                type: integer
                example: 42
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token generated from Settings > API Integration. Format: Bearer
        <token>

````