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

# Convert lead to deal

> Converts a lead into a pipeline card (deal) in the specified funnel and optional stage.



## OpenAPI

````yaml /api-reference/voxys_crm_swagger.json post /api/v1/accounts/{account_id}/leads/{lead_id}/convert
openapi: 3.1.0
info:
  title: Voxys Connect - CRM APIs
  description: >-
    CRM API documentation for Voxys Connect, covering Leads, Companies,
    Pipelines, Follow-up Tasks, and Conversation CRM.
  version: 1.0.0
  contact:
    email: support@voxys.ai
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://connect.voxys.ai
security:
  - userApiKey: []
tags:
  - name: Leads
    description: >-
      Manage CRM leads including creation, status changes, notes, and
      conversion.
  - name: Companies
    description: Manage companies, their contacts, timelines, and duplicate merging.
  - name: Pipelines
    description: Manage sales funnels (pipelines), their stages, and kanban cards.
  - name: Follow-up Tasks
    description: >-
      Create and manage follow-up tasks attached to leads, deals, or
      conversations.
  - name: Conversation CRM
    description: >-
      CRM panel within a conversation: link pipelines, leads, and convert to
      deal.
paths:
  /api/v1/accounts/{account_id}/leads/{lead_id}/convert:
    parameters:
      - $ref: '#/components/parameters/account_id'
      - name: lead_id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the lead to convert.
    post:
      tags:
        - Leads
      summary: Convert lead to deal
      description: >-
        Converts a lead into a pipeline card (deal) in the specified funnel and
        optional stage.
      operationId: convert-lead-to-deal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lead_convert_payload'
      responses:
        '201':
          description: Lead converted; returns the new funnel card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/funnel_card'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '404':
          description: Lead or funnel not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation_error'
components:
  parameters:
    account_id:
      name: account_id
      in: path
      required: true
      schema:
        type: integer
      description: The numeric ID of the account.
  schemas:
    lead_convert_payload:
      type: object
      required:
        - funnel_id
      properties:
        funnel_id:
          type: integer
          example: 3
        funnel_stage_id:
          type: integer
          nullable: true
          example: 7
    funnel_card:
      type: object
      properties:
        id:
          type: integer
          example: 55
        funnel_id:
          type: integer
          example: 3
        funnel_stage_id:
          type: integer
          example: 7
        lead:
          $ref: '#/components/schemas/lead'
        position:
          type: integer
          example: 1
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    error_response:
      type: object
      properties:
        error:
          type: string
          example: Unauthorized
    validation_error:
      type: object
      properties:
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            name:
              - can't be blank
    lead:
      type: object
      properties:
        id:
          type: integer
          example: 42
        custom_name:
          type: string
          example: Enterprise Deal - Q3
        status:
          type: string
          enum:
            - open
            - won
            - lost
            - snoozed
          example: open
        lead_value:
          type: number
          format: float
          nullable: true
          example: 15000
        lead_currency:
          type: string
          nullable: true
          example: USD
        position:
          type: integer
          nullable: true
          example: 1
        notes:
          type: string
          nullable: true
          example: Prospect from trade show
        assigned_agent:
          $ref: '#/components/schemas/agent_summary'
          nullable: true
        company:
          $ref: '#/components/schemas/company_summary'
          nullable: true
        conversation_id:
          type: integer
          nullable: true
          example: 100
        custom_attributes:
          $ref: '#/components/schemas/custom_attributes'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    agent_summary:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Jane Smith
        email:
          type: string
          format: email
          example: jane@example.com
        avatar_url:
          type: string
          format: uri
          nullable: true
    company_summary:
      type: object
      properties:
        id:
          type: integer
          example: 10
        name:
          type: string
          example: Acme Corp
        domain:
          type: string
          example: acme.com
          nullable: true
    custom_attributes:
      type: object
      description: Flexible key-value map of custom attributes defined for the account.
      additionalProperties: true
      example:
        industry: Technology
        annual_revenue: 500000
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: >-
        API access token for authentication. Obtain from your Voxys Connect
        profile settings.

````