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

# List Customers

> Retrieve a paginated list of customers for the specified team.
Supports search, pagination, and sorting capabilities.




## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/dev/teams/{teamId}/customers
openapi: 3.0.1
info:
  title: Lukittu API
  description: >
    The Lukittu API provides comprehensive license management and verification
    services for software products.


    ## Authentication


    **Client Endpoints** (`/api/v1/client/*`): No authentication required. These
    are public endpoints for license verification.


    **Developer Endpoints** (`/api/v1/dev/*`): Require API key authentication
    via Bearer token.


    ## API Types


    - **Client API**: Used by your software to verify licenses, send heartbeats,
    and download releases

    - **Developer API**: Used for programmatic license management from your
    backend systems


    ## Rate Limiting


    All endpoints are rate-limited to prevent abuse. If you exceed the rate
    limit, you'll receive a 429 status code.


    ## Response Format


    All responses follow a consistent format with `data` and `result` objects:


    ```json

    {
      "data": {}, // Response data (null for errors)
      "result": {
        "timestamp": "2023-09-15T14:30:00Z",
        "valid": true,
        "details": "Human-readable message",
        "code": "SUCCESS_CODE" // Optional error/success code
      }
    }

    ```
  version: 1.0.0
  contact:
    name: Lukittu Community
    url: https://discord.lukittu.com
servers:
  - url: https://app.lukittu.com
    description: Production server
security: []
tags:
  - name: Client - Verify
    description: >
      Client endpoints for license verification, heartbeat monitoring, and file
      downloads.

      These endpoints are used directly by your software applications.
  - name: Dev - Licenses
    description: |
      Developer endpoints for license management operations.
      These endpoints require API key authentication.
  - name: Dev - Customers
    description: |
      Developer endpoints for customer management operations.
      These endpoints require API key authentication.
  - name: Dev - Releases
    description: |
      Developer endpoints for release management operations.
      These endpoints require API key authentication.
  - name: Dev - Statistics
    description: |
      Developer endpoints for retrieving team usage statistics.
      These endpoints require API key authentication.
paths:
  /api/v1/dev/teams/{teamId}/customers:
    get:
      tags:
        - Dev - Customers
      summary: List Customers
      description: |
        Retrieve a paginated list of customers for the specified team.
        Supports search, pagination, and sorting capabilities.
      operationId: listCustomers
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: sortColumn
          in: query
          required: false
          description: Column to sort by
          schema:
            type: string
            enum:
              - fullName
              - createdAt
              - updatedAt
              - email
              - username
            default: createdAt
          example: createdAt
        - name: sortDirection
          in: query
          required: false
          description: Sort direction
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          example: desc
        - name: search
          in: query
          required: false
          description: Search customers by email, full name, or username
          schema:
            type: string
            minLength: 1
            maxLength: 255
          example: john@example.com
      responses:
        '200':
          description: Customers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      hasNextPage:
                        type: boolean
                        description: Whether there are more customers available
                        example: true
                      customers:
                        type: array
                        items:
                          $ref: '#/components/schemas/CustomerData'
                  result:
                    $ref: '#/components/schemas/StandardResult'
              example:
                data:
                  hasNextPage: false
                  customers:
                    - id: 789e0123-e89b-12d3-a456-426614174222
                      email: john@example.com
                      fullName: John Doe
                      username: johndoe
                      metadata:
                        - key: tier
                          value: premium
                          locked: false
                      address:
                        street: 123 Main St
                        city: Anytown
                        state: CA
                        country: US
                        postalCode: '12345'
                      discordAccount:
                        id: 111e2222-e89b-12d3-a456-426614174999
                        customerId: 789e0123-e89b-12d3-a456-426614174222
                        discordId: '123456789012345678'
                        username: johndoe_discord
                        avatar: a1b2c3d4e5f6g7h8i9j0
                        globalName: JohnD
                        createdAt: '2023-09-15T14:30:00Z'
                        updatedAt: '2023-09-15T14:30:00Z'
                      teamId: 123e4567-e89b-12d3-a456-426614174000
                      createdByUserId: 456e7890-e89b-12d3-a456-426614174111
                      createdAt: '2023-09-15T14:30:00Z'
                      updatedAt: '2023-09-15T14:30:00Z'
                    - id: 890f1234-e89b-12d3-a456-426614174333
                      email: jane@example.com
                      fullName: Jane Smith
                      username: janesmith
                      metadata: []
                      address:
                        street: 456 Oak Ave
                        city: Elsewhere
                        state: NY
                        country: US
                        postalCode: '54321'
                      discordAccount: null
                      teamId: 123e4567-e89b-12d3-a456-426614174000
                      createdByUserId: 456e7890-e89b-12d3-a456-426614174111
                      createdAt: '2023-09-14T10:15:00Z'
                      updatedAt: '2023-09-14T10:15:00Z'
                result:
                  timestamp: '2023-09-15T14:30:00Z'
                  valid: true
                  details: Customers found
        4XX:
          $ref: '#/components/responses/StandardError'
        5XX:
          $ref: '#/components/responses/StandardError'
      security:
        - bearerAuth: []
components:
  parameters:
    TeamId:
      name: teamId
      in: path
      required: true
      description: >-
        Your team's UUID. You can find this value in your team's settings on the
        Lukittu dashboard.
      schema:
        $ref: '#/components/schemas/UUID'
      example: 123e4567-e89b-12d3-a456-426614174000
    Page:
      name: page
      in: query
      required: false
      description: Page number for pagination (1-based)
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
    PageSize:
      name: pageSize
      in: query
      required: false
      description: Number of items per page
      schema:
        type: integer
        enum:
          - 10
          - 25
          - 50
          - 100
        default: 25
      example: 25
  schemas:
    CustomerData:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          description: Unique customer identifier
        email:
          type: string
          format: email
          nullable: true
          description: Customer email address
        fullName:
          type: string
          nullable: true
          description: Customer full name
        username:
          type: string
          nullable: true
          description: Customer username
        metadata:
          $ref: '#/components/schemas/Metadata'
        address:
          $ref: '#/components/schemas/Address'
          nullable: true
          description: Customer address information
        discordAccount:
          $ref: '#/components/schemas/DiscordAccount'
          nullable: true
          description: Associated Discord account information
        teamId:
          $ref: '#/components/schemas/UUID'
          description: Team that owns this customer
        createdByUserId:
          $ref: '#/components/schemas/UUID'
          description: User who created this customer record
        createdAt:
          type: string
          format: date-time
          description: Customer record creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Customer record last update timestamp
      required:
        - id
        - teamId
        - createdByUserId
        - createdAt
        - updatedAt
    StandardResult:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the response was generated
        valid:
          type: boolean
          description: Indicates whether the operation was successful
        details:
          type: string
          description: Human-readable description of the result
      required:
        - timestamp
        - valid
        - details
    UUID:
      type: string
      format: uuid
      description: UUID v4 identifier
    Metadata:
      type: array
      description: Key-value metadata pairs
      items:
        type: object
        properties:
          key:
            type: string
            description: Metadata key
          value:
            type: string
            description: Metadata value
          locked:
            type: boolean
            description: Whether this metadata field is locked from client modification
        required:
          - key
          - value
          - locked
    Address:
      type: object
      properties:
        street:
          type: string
          nullable: true
          description: Street address
        city:
          type: string
          nullable: true
          description: City
        state:
          type: string
          nullable: true
          description: State or province
        country:
          type: string
          nullable: true
          description: Country
        postalCode:
          type: string
          nullable: true
          description: Postal or ZIP code
    DiscordAccount:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
          description: Discord account record ID
        customerId:
          $ref: '#/components/schemas/UUID'
          description: Associated customer ID
        discordId:
          type: string
          pattern: ^\d{17,19}$
          description: Discord user ID (snowflake)
        username:
          type: string
          description: Discord username
        avatar:
          type: string
          nullable: true
          description: Discord avatar hash (null if no custom avatar)
        createdAt:
          type: string
          format: date-time
          description: Discord account record creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Discord account record last update timestamp
      required:
        - id
        - customerId
        - discordId
        - username
        - createdAt
        - updatedAt
    ErrorResponse:
      type: object
      properties:
        data:
          type: object
          description: Additional error-related data
          nullable: true
        result:
          allOf:
            - $ref: '#/components/schemas/StandardResult'
            - type: object
              properties:
                valid:
                  type: boolean
                  enum:
                    - false
                  description: Always false for error responses
                code:
                  type: string
                  description: Error code indicating the specific issue
                  enum:
                    - INTERNAL_SERVER_ERROR
                    - BAD_REQUEST
                    - LICENSE_NOT_FOUND
                    - IP_LIMIT_REACHED
                    - HWID_LIMIT_REACHED
                    - PRODUCT_NOT_FOUND
                    - CUSTOMER_NOT_FOUND
                    - LICENSE_EXPIRED
                    - LICENSE_SUSPENDED
                    - TEAM_NOT_FOUND
                    - RATE_LIMIT
                    - HARDWARE_IDENTIFIER_BLACKLISTED
                    - COUNTRY_BLACKLISTED
                    - IP_BLACKLISTED
                    - RELEASE_NOT_FOUND
                    - FORBIDDEN
                    - UNAUTHORIZED
                    - INVALID_SESSION_KEY
                    - NO_ACCESS_TO_RELEASE
                    - RELEASE_ARCHIVED
                    - RELEASE_DRAFT
              required:
                - code
      required:
        - result
  responses:
    StandardError:
      description: >
        Standard API error response. All errors follow the same `{data, result}`
        structure.

        The HTTP status code indicates the general error category, while
        `result.code` provides specific error details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: apiKey
      description: >
        API key authentication for development endpoints.


        You can create API keys in your team's settings on the Lukittu
        dashboard.

        Include the API key in the Authorization header as: `Bearer
        YOUR_API_KEY`


        Example:

        ```

        Authorization: Bearer lukittu_api_key_abc123def456...

        ```

````