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

# List campaigns

> Base model view set providing standardized CRUD operations and error handling.

This view set enforces consistent response formats, error handling patterns,
and logging across all API endpoints. Subclasses must override the class
variables below.



## OpenAPI

````yaml /openapi/commercial.yaml get /api/v1/campaigns
openapi: 3.0.3
info:
  title: Commercial Service API
  version: 1.0.0
  description: |2-

        **Commercial Service API** - Lead management and campaign workflow system.

        ## Versioning
        The API uses URL path versioning (e.g., `/api/v1/`, `/api/v2/`).
        Current version: **v1**
        
servers:
  - url: https://api.capedigital.co.ke/commercial
    description: Production
  - url: http://localhost:8000
    description: Local
security: []
paths:
  /api/v1/campaigns:
    get:
      tags:
        - Campaigns
      summary: List campaigns
      description: >-
        Base model view set providing standardized CRUD operations and error
        handling.


        This view set enforces consistent response formats, error handling
        patterns,

        and logging across all API endpoints. Subclasses must override the class

        variables below.
      operationId: campaigns_list
      parameters:
        - in: query
          name: bse
          schema:
            type: string
          description: >-
            Filter by BSE UUID. Returns campaigns whose originating lead was
            created by this user (`Lead.created_by`).
        - in: query
          name: category
          schema:
            type: string
          description: >-
            Filter by LeadCategory name, case-insensitive. e.g. `Direct`,
            `Agency`, `Digital`, `Government`.
        - name: cursor
          required: false
          in: query
          description: The pagination cursor value.
          schema:
            type: string
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
        - in: query
          name: search
          schema:
            type: string
          description: >-
            Case-insensitive substring search across campaign reference, company
            name, contact phone, and contact email.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCampaignList'
              examples:
                CampaignResponse:
                  value:
                    next: http://api.example.org/accounts/?cursor=cD00ODY%3D"
                    previous: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
                    results:
                      - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                        reference: CP-2024-001
                        start_date: '2024-02-01'
                        end_date: '2024-02-28'
                        status: Campaign In Progress
                        node: on_air
                        company_name: ABC Corporation
                        products:
                          - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                            name: TV Spot 30s
                        created_at: '2024-01-15T08:00:00Z'
                        updated_at: '2024-01-15T08:00:00Z'
                  summary: Campaign response
          description: ''
      security:
        - bearerAuth: []
components:
  schemas:
    PaginatedCampaignList:
      type: object
      required:
        - results
      properties:
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
        results:
          type: array
          items:
            $ref: '#/components/schemas/Campaign'
    Campaign:
      type: object
      description: Campaign Serializer
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        reference:
          type: string
          nullable: true
          description: Generated reference string
          maxLength: 30
        name:
          type: string
          description: Campaign name (captured at client commitment)
          maxLength: 255
        start_date:
          type: string
          format: date
          description: Campaign start date
        end_date:
          type: string
          format: date
          description: Campaign end date
        status:
          type: string
          description: Lead status
          maxLength: 50
        node:
          type: string
          description: Workflow Node
          maxLength: 50
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      required:
        - created_at
        - end_date
        - id
        - node
        - start_date
        - status
        - updated_at
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Enter your JWT token in the format: Bearer <token>'

````