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

# Listar Leads

> Retorna uma lista paginada de leads do workspace. Use os filtros para refinar os resultados.



## OpenAPI

````yaml GET /v1/leads
openapi: 3.0.1
info:
  title: Integrabot API
  version: 1.0.0
  description: >-
    A API do Integrabot permite gerenciar leads, agents e integrações de forma
    programática. Use esta API para criar leads a partir de formulários web,
    sincronizar contatos com seu CRM ou automatizar fluxos de trabalho com os
    agents de IA do Integrabot.
  contact:
    name: Suporte Integrabot
    email: hello@integrabot.ai
    url: https://docs.integrabot.ai
servers:
  - url: https://api.integrabot.ai
    description: Produção
security:
  - bearerAuth: []
paths:
  /v1/leads:
    get:
      tags:
        - Leads
      summary: Listar Leads
      description: >-
        Retorna uma lista paginada de leads do workspace. Use os filtros para
        refinar os resultados.
      operationId: listLeads
      parameters:
        - name: status
          in: query
          required: false
          description: Filtrar por status do lead.
          schema:
            type: string
            enum:
              - new
              - contacted
              - qualified
              - lost
              - converted
        - name: type
          in: query
          required: false
          description: Filtrar por canal de origem.
          schema:
            type: string
            enum:
              - web
              - telegram
              - email
              - manual
        - name: agent_id
          in: query
          required: false
          description: Filtrar por agent. Use o UUID do agent.
          schema:
            type: string
            format: uuid
        - name: search
          in: query
          required: false
          description: Buscar por nome, e-mail ou telefone.
          schema:
            type: string
        - name: date_from
          in: query
          required: false
          description: Data inicial para filtro (formato ISO 8601).
          schema:
            type: string
            format: date
        - name: date_to
          in: query
          required: false
          description: Data final para filtro (formato ISO 8601).
          schema:
            type: string
            format: date
        - name: page
          in: query
          required: false
          description: Número da página.
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          description: 'Itens por página. Máximo: 100.'
          schema:
            type: integer
            default: 25
            maximum: 100
      responses:
        '200':
          description: Lista paginada de leads.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedLeads'
              example:
                data:
                  - id: 1234
                    name: Maria Silva
                    type: web
                    phone_number: '5511999998888'
                    email: maria@exemplo.com
                    status: new
                    agent_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    custom_fields:
                      empresa: Acme Ltda
                    created_at: '2025-01-15T10:30:00Z'
                    updated_at: '2025-01-15T14:22:00Z'
                  - id: 1235
                    name: João Santos
                    type: web
                    phone_number: null
                    email: joao@empresa.com
                    status: contacted
                    agent_id: null
                    custom_fields: {}
                    created_at: '2025-01-14T09:00:00Z'
                    updated_at: '2025-01-14T11:30:00Z'
                meta:
                  current_page: 1
                  per_page: 25
                  total: 150
                  last_page: 6
        '401':
          description: Token de API inválido ou ausente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
components:
  schemas:
    PaginatedLeads:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Lead'
        meta:
          type: object
          properties:
            current_page:
              type: integer
              example: 1
            per_page:
              type: integer
              example: 25
            total:
              type: integer
              example: 150
            last_page:
              type: integer
              example: 6
    ErrorUnauthorized:
      type: object
      properties:
        error:
          type: string
          example: Unauthorized
        message:
          type: string
          example: Token de API inválido ou ausente.
    Lead:
      type: object
      properties:
        id:
          type: integer
          example: 1234
        name:
          type: string
          example: Maria Silva
        type:
          type: string
          enum:
            - web
            - telegram
            - email
            - manual
          example: web
        phone_number:
          type: string
          nullable: true
          example: '5511999998888'
        email:
          type: string
          nullable: true
          example: maria@exemplo.com
        status:
          type: string
          enum:
            - new
            - contacted
            - qualified
            - lost
            - converted
          example: new
        agent_id:
          type: string
          format: uuid
          nullable: true
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        custom_fields:
          type: object
          nullable: true
          additionalProperties:
            type: string
          example:
            empresa: Acme Ltda
            cidade: São Paulo
        created_at:
          type: string
          format: date-time
          example: '2025-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-01-15T14:22:00Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key starting with sk_

````