API endpoint for retrieving lead conversion options including matching contacts, accounts, field mappings, and layout preferences. Helps determine available conversion paths before performing actual lead conversion.
{
"openapi": "3.1.0",
"info": {
"title": "Zoho CRM Lead Conversion Options API",
"description": "API endpoint for retrieving lead conversion options including matching contacts, accounts, field mappings, and layout preferences. Helps determine available conversion paths before performing actual lead conversion.",
"version": "8.0"
},
"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}/__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"
}
],
"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"
]
}
]
}
}
},
"components": {
"parameters": {
"LeadId": {
"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": {
"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 access to Leads module in Zoho CRM"
}
}
}
}
}
}
}