Convert Lead

Table of Contents

Description

This task is used to convert a lead into a contact, deal, and account in Zoho CRM.

Syntax

<variable> = zoho.crm.convertLead(<lead_id>, <values>, <connection>);

where,

ParamsData typeDescription
<variable>KEY-VALUEspecifies the response message returned by Zoho CRM. It represents the IDs of the new records created in Contacts, Deals, and Accounts module against its respective API names.
<lead_id>NUMBER

specifies the record ID of the lead that needs to be converted.

Learn how to fetch the ID of a record after creating it or fetching it.

<values>KEY-VALUEspecifies the input value to the task. Refer to this Zoho CRM API page for more details.

<connection>

(Optional)

TEXT

specifies the name of the connection

Note: 

 

Example 1

The following script converts the lead with ID - 2303XXXXXXXXXXXXXXX, and creates a new record in Contacts, Deals, and Accounts module.

 deal_values = Map();
 deal_values.put("Deal_Name","Jake");
 deal_values.put("Closing_Date","2018-12-06");
 deal_values.put("Stage","Closed Won");
 response = zoho.crm.convertLead(2303XXXXXXXXXXXXXXX,{"Deals":deal_values});

where,

response
variable holding the response returned by Zoho CRM, which represents the IDs of the new records created in Contacts, Deals, and Accounts module
2303XXXXXXXXXXXXXXX
is the NUMBER that represents the ID of the lead that needs to be converted
"Deals"
is the key of TEXT data type which represents the values of the new record to be created in the Deals Module
 deal_values
is the KEY-VALUE variable that holds the additional values that are required to create a new record in the Deals Module
 "Deal_Name"  
 "Closing_Date"  
 "Stage"  
are the API names of Zoho CRM fields. They are of TEXT data type

Example 2

The following script converts the lead with ID - 2303XXXXXXXXXXXXXXX and associates it to the specified existing account and contact. Here,

  •  Since the overwrite key is set to true, the specified account and contact are overwritten with the data of the converting lead.
  • No record is created in the Deals module, as the additional values required for creating a deal are not provided.
 values_map = Map();
 values_map.put("overwrite",true);
 values_map.put("Accounts","2303XXXXXXXXXXXXXXX");
 values_map.put("Contacts","2303XXXXXXXXXXXXXXX");
 response = zoho.crm.convertLead(2303XXXXXXXXXXXXXXX,values_map);

where,

 values_map
is the KEY-VALUE variable that holds the IDs of the existing account and contact

Note: Refer this for the instructions to get API names of the CRM modules and fields.

Response Format

Success Response

  • The success response returned is of the following format

     {
     "Contacts":"2303XXXXXXXXXXXXXXX",
     "Deals":"2303XXXXXXXXXXXXXXX",
     "Accounts":"2303XXXXXXXXXXXXXXX"
     }

  • The success response returned when the values for the deal is not provided is of the following formatt

     {
     "Contacts":"2303XXXXXXXXXXXXXXX",
     "Deals":null
     "Accounts":"2303XXXXXXXXXXXXXXX"
     }

Failure Response

  • The failure response returned for incorrect or non-existent lead ID is of the following format

     {
     "code":"INVALID_DATA",
     "details":{},
     "message":"the related id given seems to be invalid",
     "status":"error"
     }

  • The failure response returned for providing a lead ID that has been already converted is of the following format

     {
     "code":"ID_ALREADY_CONVERTED",
     "details":{},
     "message":"id already converted",
     "status":"error"
     }

Related Links