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 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 account field mappings available - type: 'null' description: No field mappings available for conversion modules_with_multiple_layouts: oneOf: - type: array description: Modules that have multiple layout options available maxItems: 20 items: type: object description: Module with multiple layouts additionalProperties: false properties: api_name: type: string description: API name of the module maxLength: 100 id: type: string description: Unique identifier of the module (int64 as string) pattern: ^[0-9]+$ maxLength: 50 required: - api_name - id - type: 'null' description: No modules have multiple layout options required: - module_preference - Contacts - Accounts - preference_field_matched_value - modules_with_multiple_layouts '204': description: No conversion options available for this lead. The lead may not have any matching records or conversion options. '400': description: Bad request due to invalid lead ID, record approval issues, or record locking conflicts. content: application/json: schema: oneOf: - type: object description: Standard error response for invalid data or record issues additionalProperties: false properties: code: type: string description: Error code indicating the type of failure enum: - INVALID_DATA - NOT_APPROVED - RECORD_LOCKED message: type: string description: Human-readable error message describing the issue maxLength: 500 status: type: string description: Status of the request enum: - error details: type: object description: Additional error details including resource path information additionalProperties: false properties: resource_path_index: type: integer format: int32 description: Index of the resource path parameter that caused the error required: - resource_path_index required: - code - message - status - details security: - iam-oauth2-schema: - ZohoCRM.modules.leads.READ tags: - Leads components: schemas: EntityReference: type: object description: Reference to a CRM entity with ID and name required: - name - id additionalProperties: false properties: name: type: string description: Name of the entity maxLength: 200 id: type: string description: Unique identifier of the entity record (int64 as string) maxLength: 20 ConversionScheduled: type: object description: Lead conversion scheduled for background processing required: - code - message - status - details additionalProperties: false properties: code: type: string enum: - SCHEDULED description: Status code indicating conversion was scheduled message: type: string description: Human-readable message maxLength: 500 status: type: string enum: - success description: Overall status details: type: object description: Job details required: - job_id additionalProperties: false properties: job_id: type: string description: Unique job identifier maxLength: 20 ConversionSuccessWrapper: type: object description: Wrapper for successful conversion response required: - data additionalProperties: false properties: data: type: array description: Array of conversion results maxItems: 100 items: $ref: '#/components/schemas/ConversionSuccess' ValidationError: type: object description: Validation error details required: - status - code - message - details additionalProperties: false properties: status: type: string enum: - error description: Error status indicator code: type: string enum: - MANDATORY_NOT_FOUND - MAPPING_MISMATCH - INVALID_DATA - DUPLICATE_DATA - CANNOT_PERFORM_ACTION - NOT_ALLOWED - NOT_REVIEWED description: Error code identifying the type of validation failure message: type: string description: Human-readable error message maxLength: 500 details: type: object description: Additional error context and affected field information additionalProperties: true properties: api_name: type: string description: API name of the affected field maxLength: 100 json_path: type: string description: JSONPath to the affected field in the request maxLength: 200 mapped_field: type: string description: Name of the field that has a mapping relationship maxLength: 100 expected_data_type: type: string description: Expected data type for the field maxLength: 50 maximum_length: type: integer format: int32 description: Maximum allowed length for the field ValidationErrorWrapper: type: object description: Wrapper for validation error responses required: - data additionalProperties: false properties: data: type: array description: Array of validation errors maxItems: 100 items: $ref: '#/components/schemas/ValidationError' ConversionRequestWrapper: type: object description: Wrapper object containing array of conversion requests required: - data additionalProperties: false properties: data: type: array description: Array of lead conversion configurations maxItems: 100 items: $ref: '#/components/schemas/ConversionRequest' DealConversion: type: object description: Deal record configuration for lead conversion required: - Deal_Name - Pipeline - Stage - Closing_Date additionalProperties: false properties: Deal_Name: type: string description: Name of the Deal maxLength: 120 Campaign_Source: type: string description: Campaign source associated with this Deal maxLength: 100 Amount: type: number format: double description: Expected revenue amount for the Deal Contact_Role: type: string description: Role of the Contact in this Deal maxLength: 50 Pipeline: type: string description: Sales pipeline for the Deal. Must match an existing pipeline in the CRM. maxLength: 100 $move_attachments: type: boolean description: If true, moves attachments from the Lead to the Deal Stage: type: string description: Current stage of the Deal within the specified Pipeline. Must be valid for the chosen Pipeline. maxLength: 100 Closing_Date: type: string format: date description: 'Expected closing date for the Deal (ISO 8601 date format: YYYY-MM-DD)' Type: type: string description: Type of Deal (e.g., New Business, Existing Business) maxLength: 50 Probability: type: integer format: int32 minimum: 0 maximum: 100 description: Win probability percentage (0-100) Lead_Source: type: string description: Source from which the Lead originated maxLength: 100 Next_Step: type: string description: Next action or milestone for the Deal maxLength: 200 Description: type: string description: Detailed description of the Deal maxLength: 32000 ErrorResponse: type: object description: Root-level error response without data wrapper required: - status - code - message - details additionalProperties: false properties: status: type: string enum: - error description: Error status indicator code: type: string enum: - INVALID_DATA - ID_ALREADY_CONVERTED - CANNOT_PERFORM_ACTION - NOT_ALLOWED - REQUIRED_PARAM_MISSING - NOT_REVIEWED description: Error code message: type: string description: Error message maxLength: 500 details: type: object description: Error details additionalProperties: true properties: resource_path_index: type: integer format: int32 description: Index of the resource path that caused the error param_name: type: string description: Name of the missing or invalid parameter maxLength: 100 ConversionRequest: type: object description: Configuration for converting a single lead additionalProperties: false properties: overwrite: type: boolean description: If true, overwrites existing Account or Contact data when add_to_existing_record is enabled. Default is false. default: false notify_lead_owner: type: boolean description: If true, sends email notification to the Lead owner about the conversion. Default is false. default: false notify_new_entity_owner: type: boolean description: If true, notifies the owner(s) of newly created Contact, Account, or Deal records. Default is false. default: false add_to_existing_record: type: boolean description: When true, associates the Lead with an existing Account or Contact instead of creating duplicates. assign_to: type: object description: Specifies the user to assign the converted records to. If omitted, records are assigned to the current Lead owner. required: - id additionalProperties: false properties: id: type: string description: Zoho CRM user ID (int64 as string) maxLength: 20 Deals: $ref: '#/components/schemas/DealConversion' carry_over_tags: type: object description: Configuration for carrying over tags from the Lead to converted records additionalProperties: false properties: Contacts: type: object description: Tag carryover settings for Contact records additionalProperties: true Accounts: type: object description: Tag carryover settings for Account records additionalProperties: true Deals: type: object description: Tag carryover settings for Deal records additionalProperties: true ConversionScheduledWrapper: type: object description: Wrapper for scheduled conversion response required: - data additionalProperties: false properties: data: type: array description: Array containing the scheduled job information maxItems: 1 items: $ref: '#/components/schemas/ConversionScheduled' ConversionSuccess: type: object description: Successful lead conversion result required: - code - message - status - details additionalProperties: false properties: code: type: string enum: - SUCCESS description: Status code indicating successful conversion message: type: string description: Human-readable message describing the conversion result maxLength: 500 status: type: string enum: - success description: Overall status of the conversion operation details: type: object description: Details of created records including their IDs and names required: - Contacts - Deals - Accounts additionalProperties: false properties: Contacts: $ref: '#/components/schemas/EntityReference' Deals: oneOf: - $ref: '#/components/schemas/EntityReference' - type: 'null' description: No Deal was created during conversion description: Deal record information, or null if no Deal was created Accounts: oneOf: - $ref: '#/components/schemas/EntityReference' - type: 'null' description: No Account was created during conversion description: Account record information, or null if no Account was created parameters: LeadId: name: leadId in: path required: true description: Unique identifier of the Lead record to convert. Must be a valid Lead ID that exists in the CRM and has not been previously converted. schema: type: string format: int64 JobId: name: job_id in: query required: true description: Identifier of the mass convert job to fetch status for. schema: type: string maxLength: 255 LeadId_2: name: leadId in: path required: true description: Unique identifier of the Lead record to retrieve conversion options for schema: type: string format: int64 securitySchemes: iam-oauth2-schema: $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema x-entity: Helpcenter