API endpoint for converting Leads into Contacts, Accounts, and Deals within Zoho CRM. Supports configurable conversion options including owner assignment, notification preferences, and tag carryover.
{
"openapi": "3.1.0",
"info": {
"title": "Zoho CRM Lead Conversion API",
"description": "API endpoint for converting Leads into Contacts, Accounts, and Deals within Zoho CRM. Supports configurable conversion options including owner assignment, notification preferences, and tag carryover.",
"version": "8"
},
"servers": [
{
"url": "https://zohoapis.{dc}/crm/{version}",
"description": "API Server URL",
"variables": {
"dc": {
"enum": [
"com",
"eu",
"in",
"cn",
"au"
],
"default": "com",
"description": "API Server URL TLD"
},
"version": {
"default": "v8",
"description": "API Version"
}
}
}
],
"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"
]
}
]
}
}
},
"components": {
"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"
}
}
},
"schemas": {
"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"
}
}
}
},
"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
}
}
}
}
},
"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
}
}
},
"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"
}
}
}
},
"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"
}
}
}
}
},
"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"
}
}
}
},
"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
}
}
}
}
},
"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
}
}
},
"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"
}
}
}
},
"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"
}
}
}
}
},
"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
}
}
}
}
}
},
"securitySchemes": {
"iam-oauth2-schema": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://accounts.zoho.com/oauth/v2/auth",
"tokenUrl": "https://accounts.zoho.com/oauth/v2/token",
"refreshUrl": "https://accounts.zoho.com/oauth/v2/token",
"scopes": {
"ZohoCRM.modules.leads.READ": "Read Records in Leads module",
"ZohoCRM.modules.leads.CREATE": "Create Records in Leads module"
}
}
}
}
}
}
}