Zoho Leads API

openapi: 3.1.0
info:
  title: Helpcenter Leads API
  version: 1.0.0
tags:
- name: Leads
paths:
  /Leads/{leadId}/actions/convert:
    post:
      summary: Convert a Lead
      description: Converts a Lead record into Contact, Account, and/or Deal records. Allows configuration of conversion behavior including overwrite settings, notifications, owner assignment, and tag carryover.
      operationId: convertLead
      parameters:
      - $ref: '#/components/parameters/LeadId'
      requestBody:
        description: Lead conversion configuration including optional Deal creation, owner assignment, notification preferences, and tag carryover settings.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionRequestWrapper'
      responses:
        '200':
          description: Lead successfully converted. Returns details of created Contact, Account, and Deal records with their IDs and names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionSuccessWrapper'
        '202':
          description: Lead conversion request accepted and scheduled for processing, or contains validation errors.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ConversionScheduledWrapper'
                - $ref: '#/components/schemas/ValidationErrorWrapper'
        '400':
          description: Bad request due to invalid input data, malformed request, or attempting to convert an already converted Lead.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ValidationErrorWrapper'
                - $ref: '#/components/schemas/ErrorResponse'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.leads.CREATE
      tags:
      - Leads
  /Leads/actions/mass_convert:
    post:
      operationId: massConvert
      summary: Mass convert leads
      description: Start a scheduled mass-convert job that converts multiple leads into other modules (Deals/Contacts/Accounts) according to provided options. Max 50 lead IDs per request.
      requestBody:
        description: Payload describing conversion options and lead ids to be converted.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request payload for mass convert operation.
              additionalProperties: false
              properties:
                ids:
                  type: array
                  description: Array of Lead record IDs to be converted. Maximum 50 IDs.
                  items:
                    type: string
                    description: A lead record id.
                    maxLength: 255
                  maxItems: 50
                Deals:
                  type: object
                  description: Optional Deal record template to use when converting leads to Deals. If provided, it must include all mandatory Deal fields, and may include any other Deal fields as needed.
                  additionalProperties: false
                  properties:
                    Deal_Name:
                      type: string
                      description: Name of the deal to be created for converted leads.
                      maxLength: 255
                  required:
                  - Deal_Name
                assign_to:
                  type: object
                  description: User assignment information for the converted records. Use Get Users API to retrieve user id.
                  additionalProperties: false
                  properties:
                    id:
                      type: string
                      description: User id to assign the converted records to.
                      maxLength: 255
                  required:
                  - id
                portal_user_type:
                  type: object
                  description: Portal user type reference for the converted contact, if applicable.
                  additionalProperties: false
                  properties:
                    id:
                      type: string
                      description: Portal user type id.
                      maxLength: 255
                  required:
                  - id
                related_modules:
                  type: array
                  description: List of related modules (Tasks/Events/Calls) to move with converted records. If present, ownership of those related records will be assigned to the user in assign_to.
                  items:
                    type: object
                    description: A related-module configuration object containing module API name and id.
                    additionalProperties: false
                    properties:
                      api_name:
                        type: string
                        description: Related module API name (e.g., Tasks, Events, Calls).
                        maxLength: 100
                      id:
                        type: string
                        description: Related module id
                        maxLength: 255
                    required:
                    - api_name
                    - id
                  maxItems: 3
                carry_over_tags:
                  type: array
                  description: List of tag objects to carry over to converted records (Contacts, Deals, Accounts supported).
                  items:
                    type: object
                    description: A tag mapping object describing target module api name and id.
                    additionalProperties: false
                    properties:
                      api_name:
                        type: string
                        description: Module API name where the tag applies.
                        maxLength: 100
                      id:
                        type: string
                        description: Module Id where the tag applies.
                        maxLength: 255
                    required:
                    - api_name
                    - id
                  maxItems: 3
                move_attachments_to:
                  type: object
                  description: Target module and record to which attachments should be moved after converting the lead (Contacts, Deals, Accounts supported).
                  additionalProperties: false
                  properties:
                    api_name:
                      type: string
                      description: Module API name where attachments will be moved.
                      maxLength: 100
                    id:
                      type: string
                      description: Module Id where attachments will be moved.
                      maxLength: 255
                  required:
                  - api_name
                  - id
                apply_assignment_threshold:
                  type: boolean
                  description: Flag to indicate whether assignment threshold rules should be applied when assigning records.Default value will be true
              required:
              - ids
      responses:
        '202':
          description: Accepted — mass convert scheduled and job id returned in details.
          content:
            application/json:
              schema:
                type: object
                description: Response returned when the mass convert job is scheduled.
                additionalProperties: false
                properties:
                  code:
                    type: string
                    description: Response code indicating the job status.
                    enum:
                    - SCHEDULED
                    maxLength: 50
                  message:
                    type: string
                    description: Human-readable message describing the result.
                    maxLength: 512
                  status:
                    type: string
                    description: Status category of the response.
                    enum:
                    - success
                    maxLength: 50
                  details:
                    type: object
                    description: Additional details about the scheduled job including job id.
                    additionalProperties: false
                    properties:
                      job_id:
                        type: string
                        description: Identifier for the scheduled mass convert job.
                        maxLength: 255
                    required:
                    - job_id
                required:
                - code
                - message
                - status
                - details
        '400':
          description: Bad Request — input validation or request-level errors.
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  description: Validation error response.
                  additionalProperties: false
                  properties:
                    code:
                      type: string
                      description: Error code.
                      enum:
                      - INVALID_REQUEST_METHOD
                      - INVALID_DATA
                      - REQUIRED_PARAM_MISSING
                      - NOT_ALLOWED
                      - MANDATORY_NOT_FOUND
                      - LIMIT_EXCEEDED
                      - EXPECTED_FIELD_MISSING
                      - AMBIGUITY_DURING_PROCESSING
                      maxLength: 100
                    message:
                      type: string
                      description: Human-readable error message.
                      maxLength: 512
                    status:
                      type: string
                      description: Error status category.
                      enum:
                      - error
                      maxLength: 50
                    details:
                      type: object
                      description: Additional error detail (field-level info, json path, expected types, limits, etc.).
                      additionalProperties: true
                  required:
                  - code
                  - message
                  - status
                  - details
                description: Possible 400 response shapes for validation and related errors.
        '403':
          description: Forbidden — no permission to perform the action.
          content:
            application/json:
              schema:
                type: object
                description: Permission error response.
                additionalProperties: false
                properties:
                  code:
                    type: string
                    description: Error code.
                    enum:
                    - NO_PERMISSION
                    maxLength: 100
                  message:
                    type: string
                    description: Human-readable message.
                    maxLength: 512
                  status:
                    type: string
                    description: Status category.
                    enum:
                    - error
                    maxLength: 50
                  details:
                    type: object
                    description: Optional details object.
                    additionalProperties: true
                required:
                - code
                - message
                - status
                - details
        '500':
          description: Internal Server Error — unexpected server-side error.
          content:
            application/json:
              schema:
                type: object
                description: Server error response.
                additionalProperties: false
                properties:
                  code:
                    type: string
                    description: Error code.
                    enum:
                    - INTERNAL_ERROR
                    maxLength: 100
                  message:
                    type: string
                    description: Human-readable message.
                    maxLength: 512
                  status:
                    type: string
                    description: Status category.
                    enum:
                    - error
                    maxLength: 50
                  details:
                    type: object
                    description: Optional details object.
                    additionalProperties: true
                required:
                - code
                - message
                - status
                - details
      security:
      - iam-oauth2-schema:
        - ZohoCRM.mass_convert.leads.CREATE
      tags:
      - Leads
    get:
      operationId: getJobStatus
      summary: Get mass convert job status
      description: Retrieve the status and counts of a previously scheduled mass convert job using job_id query parameter.
      parameters:
      - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: Job status response with conversion counts.
          content:
            application/json:
              schema:
                type: object
                description: Successful job status response wrapper containing an array of job status objects.
                additionalProperties: false
                properties:
                  data:
                    type: array
                    description: Array containing job status objects.
                    items:
                      type: object
                      description: Status details for a job or batch entry.
                      additionalProperties: false
                      properties:
                        Status:
                          type: string
                          description: Indicates the status of the mass convert job (completed, scheduled, in progress, failed).
                          maxLength: 50
                        Total_Count:
                          type: integer
                          format: int32
                          description: Specifies the total number of leads that were scheduled to be converted.
                        Converted_Count:
                          type: integer
                          format: int32
                          description: Specifies the number of leads that were converted.
                        Not_Converted_Count:
                          type: integer
                          format: int32
                          description: Specifies the number of leads that are yet to be converted.
                        Failed_Count:
                          type: integer
                          format: int32
                          description: Specifies the number of leads that were not converted.
                      required:
                      - Status
                      - Total_Count
                      - Converted_Count
                      - Not_Converted_Count
                      - Failed_Count
                    maxItems: 5
                required:
                - data
        '400':
          description: Bad request — validation errors for job status retrieval.
          content:
            application/json:
              schema:
                type: object
                description: Validation error response for job status retrieval.
                additionalProperties: false
                properties:
                  code:
                    type: string
                    description: Error code.
                    enum:
                    - REQUIRED_PARAM_MISSING
                    - INVALID_DATA
                    maxLength: 100
                  message:
                    type: string
                    description: Error message.
                    maxLength: 512
                  status:
                    type: string
                    description: Status category.
                    enum:
                    - error
                    maxLength: 50
                  details:
                    type: object
                    description: Details about the error (e.g., missing job_id).
                    additionalProperties: true
                required:
                - code
                - message
                - status
                - details
        '403':
          description: Forbidden — insufficient permission to retrieve job status.
          content:
            application/json:
              schema:
                type: object
                description: Permission error response.
                additionalProperties: false
                properties:
                  code:
                    type: string
                    description: Error code.
                    enum:
                    - NO_PERMISSION
                    maxLength: 100
                  message:
                    type: string
                    description: Human-readable message.
                    maxLength: 512
                  status:
                    type: string
                    description: Status category.
                    enum:
                    - error
                    maxLength: 50
                  details:
                    type: object
                    description: Optional details object.
                    additionalProperties: true
                required:
                - code
                - message
                - status
                - details
      security:
      - iam-oauth2-schema:
        - ZohoCRM.mass_convert.leads.READ
      tags:
      - Leads
  /Leads/{leadId}/__conversion_options:
    get:
      summary: Get Lead Conversion Options
      description: Retrieves available conversion options for a lead including matching contacts, accounts, field mappings, and layout preferences. This endpoint helps determine what conversion paths are available before performing the actual lead conversion.
      operationId: getLeadConversionOptions
      parameters:
      - $ref: '#/components/parameters/LeadId_2'
      responses:
        '200':
          description: Successfully retrieved lead conversion options. Returns available contacts, accounts, field mappings, and layout preferences for the specified lead.
          content:
            application/json:
              schema:
                type: object
                description: Conversion options response containing available contacts, accounts, and field mappings for lead conversion
                additionalProperties: false
                properties:
                  __conversion_options:
                    type: object
                    description: Container for all conversion option data
                    additionalProperties: false
                    properties:
                      module_preference:
                        oneOf:
                        - type: object
                          description: Preferred module for conversion based on system configuration
                          additionalProperties: false
                          properties:
                            api_name:
                              type: string
                              description: API name of the preferred module
                              maxLength: 100
                            id:
                              type: string
                              description: Unique identifier of the preferred module (int64 as string)
                              pattern: ^[0-9]+$
                              maxLength: 50
                          required:
                          - api_name
                          - id
                        - type: 'null'
                          description: No module preference set
                      Contacts:
                        oneOf:
                        - type: array
                          description: Array of existing Contact records that match the lead data
                          maxItems: 100
                          items:
                            type: object
                            description: Contact record with matching lead information
                            additionalProperties: false
                            properties:
                              Full_Name:
                                type: string
                                description: Full name of the contact
                                maxLength: 200
                              Email:
                                oneOf:
                                - type: string
                                  description: Email address of the contact
                                  format: email
                                - type: 'null'
                                  description: No email address provided
                              Layout:
                                type: object
                                description: Layout information for the contact record
                                additionalProperties: false
                                properties:
                                  name:
                                    type: string
                                    description: Name of the layout
                                    maxLength: 100
                                  id:
                                    type: string
                                    description: Unique identifier of the layout (int64 as string)
                                    pattern: ^[0-9]+$
                                    maxLength: 50
                                required:
                                - name
                                - id
                              Locked__s:
                                type: boolean
                                description: Indicates if the contact record is locked
                              Account_Name:
                                oneOf:
                                - type: object
                                  description: Associated account information
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      description: Unique identifier of the account (int64 as string)
                                      pattern: ^[0-9]+$
                                      maxLength: 50
                                    name:
                                      type: string
                                      description: Name of the account
                                      maxLength: 200
                                    Locked__s:
                                      type: boolean
                                      description: Indicates if the account record is locked
                                  required:
                                  - id
                                  - name
                                  - Locked__s
                                - type: 'null'
                                  description: No account associated with this contact
                              $editable:
                                type: boolean
                                description: Indicates if the contact record can be edited
                              id:
                                type: string
                                description: Unique identifier of the contact record (int64 as string)
                                pattern: ^[0-9]+$
                                maxLength: 50
                              $approval_state:
                                type: string
                                description: Current approval state of the contact record
                                enum:
                                - approved
                                - pending
                                - rejected
                                - approval_process_pending
                                - approval_process_rejected
                              Data_Processing_Basis:
                                oneOf:
                                - type: string
                                  description: GDPR data processing basis for the contact
                                  maxLength: 100
                                - type: 'null'
                                  description: No GDPR data processing basis specified
                            required:
                            - Full_Name
                            - Email
                            - Locked__s
                            - $editable
                            - id
                            - $approval_state
                            - Data_Processing_Basis
                        - type: 'null'
                          description: No contacts found matching the lead data
                      Accounts:
                        oneOf:
                        - type: array
                          description: Array of existing Account records that match the lead data
                          maxItems: 100
                          items:
                            type: object
                            description: Account record with matching lead information
                            additionalProperties: false
                            properties:
                              Phone:
                                oneOf:
                                - type: string
                                  description: Phone number of the account
                                  maxLength: 50
                                - type: 'null'
                                  description: No phone number provided
                              Account_Type:
                                oneOf:
                                - type: string
                                  description: Type of the account
                                  maxLength: 100
                                - type: 'null'
                                  description: No account type specified
                              Website:
                                oneOf:
                                - type: string
                                  description: Website URL of the account
                                  format: uri
                                - type: 'null'
                                  description: No website URL provided
                              Account_Name:
                                type: string
                                description: Name of the account
                                maxLength: 200
                              $editable:
                                type: boolean
                                description: Indicates if the account record can be edited
                              Locked__s:
                                type: boolean
                                description: Indicates if the account record is locked
                              $approval_state:
                                type: string
                                description: Current approval state of the account record
                                enum:
                                - approved
                                - pending
                                - rejected
                                - approval_process_pending
                                - approval_process_rejected
                              id:
                                type: string
                                description: Unique identifier of the account record (int64 as string)
                                pattern: ^[0-9]+$
                                maxLength: 50
                            required:
                            - Phone
                            - Account_Type
                            - Website
                            - Account_Name
                            - $editable
                            - Locked__s
                            - $approval_state
                            - id
                        - type: 'null'
                          description: No accounts found matching the lead data
                      preference_field_matched_value:
                        oneOf:
                        - type: object
                          description: Field mappings showing how lead values match to Contact and Account fields
                          additionalProperties: false
                          properties:
                            Contacts:
                              oneOf:
                              - type: array
                                description: Contact field mappings
                                maxItems: 50
                                items:
                                  type: object
                                  description: Field mapping for contact
                                  additionalProperties: false
                                  properties:
                                    field:
                                      type: object
                                      description: Field information
                                      additionalProperties: false
                                      properties:
                                        api_name:
                                          type: string
                                          description: API name of the field
                                          maxLength: 100
                                        field_label:
                                          type: string
                                          description: Display label of the field
                                          maxLength: 200
                                        unique:
                                          oneOf:
                                          - type: boolean
                                            description: Indicates if the field has unique constraint
                                          - type: 'null'
                                            description: Field does not have unique constraint information
                                        id:
                                          type: string
                                          description: Unique identifier of the field (int64 as string)
                                          pattern: ^[0-9]+$
                                          maxLength: 50
                                      required:
                                      - api_name
                                      - id
                                    matched_lead_value:
                                      type: string
                                      description: Value from the lead that matches this field
                                      maxLength: 500
                                  required:
                                  - field
                                  - matched_lead_value
                              - type: 'null'
                                description: No contact field mappings available
                            Accounts:
                              oneOf:
                              - type: array
                                description: Account field mappings
                                maxItems: 50
                                items:
                                  type: object
                                  description: Field mapping for account
                                  additionalProperties: false
                                  properties:
                                    field:
                                      type: object
                                      description: Field information
                                      additionalProperties: false
                                      properties:
                                        api_name:
                                          type: string
                                          description: API name o

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho/refs/heads/main/openapi/zoho-leads-api-openapi.yml