> ## 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.

# Criar Lead

> Cria um novo lead no workspace. Se já existir um lead com o mesmo telefone ou e-mail, retorna o lead existente com status 200.



## OpenAPI

````yaml POST /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:
    post:
      tags:
        - Leads
      summary: Criar Lead
      description: >-
        Cria um novo lead no workspace. Se já existir um lead com o mesmo
        telefone ou e-mail, retorna o lead existente com status 200.
      operationId: createLead
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadInput'
            examples:
              lead_web_completo:
                summary: Lead via formulário web completo
                value:
                  name: Maria Silva
                  type: web
                  phone_number: '5511999998888'
                  email: maria@exemplo.com
                  agent_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  custom_fields:
                    empresa: Acme Ltda
                    cidade: São Paulo
              lead_web:
                summary: Lead via formulário web
                value:
                  name: João Santos
                  type: web
                  email: joao@empresa.com
                  custom_fields:
                    produto_interesse: Plano Pro
      responses:
        '200':
          description: Lead já existia. Retorna o lead existente sem criar duplicata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
              example:
                id: 1001
                name: Maria Silva
                type: web
                phone_number: '5511999998888'
                email: maria@exemplo.com
                status: contacted
                agent_id: null
                custom_fields: {}
                created_at: '2025-01-10T08:15:00Z'
                updated_at: '2025-01-14T16:45:00Z'
        '201':
          description: Lead criado com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
              example:
                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
                  cidade: São Paulo
                created_at: '2025-01-15T10:30:00Z'
                updated_at: '2025-01-15T10:30:00Z'
        '401':
          description: Token de API inválido ou ausente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '422':
          description: Erro de validação. Verifique os campos enviados.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorValidation'
components:
  schemas:
    LeadInput:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Nome completo do lead
          example: Maria Silva
        type:
          type: string
          enum:
            - web
            - telegram
            - email
            - manual
          description: Canal de origem do lead
          example: web
        phone_number:
          type: string
          description: >-
            Número de telefone. Obrigatório quando aplicável. Formato:
            DDI+DDD+Numero, apenas dígitos.
          example: '5511999998888'
        email:
          type: string
          format: email
          description: Endereço de e-mail do lead
          example: maria@exemplo.com
        agent_id:
          type: string
          format: uuid
          description: >-
            UUID do agent ao qual o lead será atribuído. Se não informado, o
            lead fica sem agent.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        custom_fields:
          type: object
          description: >-
            Campos personalizados como pares chave-valor. Use para armazenar
            informações extras do lead.
          additionalProperties:
            type: string
          example:
            empresa: Acme Ltda
            cidade: São Paulo
    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'
    ErrorUnauthorized:
      type: object
      properties:
        error:
          type: string
          example: Unauthorized
        message:
          type: string
          example: Token de API inválido ou ausente.
    ErrorValidation:
      type: object
      properties:
        error:
          type: string
          example: Validation Error
        message:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            name:
              - O campo name é obrigatório.
            phone_number:
              - O campo phone_number deve estar em formato válido.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key starting with sk_

````