> ## 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 leads > Returns leads visible to the caller. All filters are optional and compose with each other — e.g. `?category=Direct&node=NODE_LEAD_NURTURING` returns nurturing Direct leads only. **N+1 note:** `lead_category`, `source`, and `partner` are fetched in a single JOIN. The `bse` filter executes one SQL subquery (`WHERE id IN (SELECT lead_id FROM lead_participants WHERE user_id = ?)`) — not a per-row lookup. ## OpenAPI ````yaml /openapi/commercial.yaml get /api/v1/leads 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/leads: get: tags: - Leads summary: List leads description: >- Returns leads visible to the caller. All filters are optional and compose with each other — e.g. `?category=Direct&node=NODE_LEAD_NURTURING` returns nurturing Direct leads only. **N+1 note:** `lead_category`, `source`, and `partner` are fetched in a single JOIN. The `bse` filter executes one SQL subquery (`WHERE id IN (SELECT lead_id FROM lead_participants WHERE user_id = ?)`) — not a per-row lookup. operationId: leads_list parameters: - in: query name: assignment_tab schema: type: string enum: - completed - ongoing - pending - rejected description: >- Filter by assignment state relative to the calling user. `pending` / `ongoing` resolve via the assignment-service; `completed` / `rejected` resolve locally via `LeadParticipant`. Users with `sales:oversight` see all leads by status regardless of assignee. Omit to return all leads visible to the caller. - in: query name: bse schema: type: string description: >- Filter by BSE UUID (`LeadParticipant.user_id`). Returns leads where this user appears as a participant. Executed as a single SQL subquery — no per-row lookups. - 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 - in: query name: node schema: type: string description: >- Filter by current workflow node code (exact match). e.g. `NODE_LEAD_NURTURING`, `GATE_PROPOSAL_APPROVED`. - 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 name, reference, contact_person, contact_phone, and contact_email. responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedLeadList' examples: LeadResponse: 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: LD-2024-001 name: ABC Corporation contact_person: Jane Smith contact_phone: '+254700000000' contact_email: jane@abc.co.ke lead_type: corporate gender: F lead_category: id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 name: New Business source: id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 name: Cold Call partner: null products: - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 name: TV Spot 30s status: New Lead node: capture created_at: '2024-01-15T08:00:00Z' updated_at: '2024-01-15T08:00:00Z' summary: Lead response description: '' security: - bearerAuth: [] components: schemas: PaginatedLeadList: 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/Lead' Lead: type: object description: Lead Serializer properties: id: type: string format: uuid readOnly: true reference: type: string nullable: true description: Generated reference string maxLength: 30 name: type: string description: Lead company name maxLength: 100 contact_person: type: string description: Contact person name maxLength: 100 contact_phone: type: string description: Contact phone number maxLength: 30 contact_email: type: string format: email description: Contact email address maxLength: 50 lead_type: enum: - individual - company type: string x-spec-enum-id: e09fc541d8e40a52 description: |- Lead classification: individual or company * `individual` - Individual * `company` - Company gender: enum: - male - female - '' - null type: string x-spec-enum-id: d6713b157e7b4bdf nullable: true description: >- Gender of individual lead (only applicable when lead_type is individual) * `male` - Male * `female` - Female lead_category: type: string format: uuid source: type: string format: uuid partner: type: string format: uuid products: type: array items: type: string format: uuid status: type: string readOnly: true description: Lead status node: type: string readOnly: true description: Workflow Node created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true required: - contact_email - contact_person - contact_phone - created_at - id - lead_category - name - node - products - source - status - updated_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Enter your JWT token in the format: Bearer ' ````