Convert Lead in Zoho CRM V8

Table of Contents

Note:

  • Each time the zoho.crm.v8.convertLead integration task is executed, it triggers an API request in the back-end. This call is deducted from the external calls limit available for the service from which the task is executed, based on your pricing plan.
  • Only actual executions that receive a response (whether success or failure) are counted, not the number of times the task appears in the script. For example, if zoho.crm.v8.convertLead integration task is placed inside a for each task that iterates five times, the number of external calls consumed will be five, even though the task appears only once in the script. 

Overview

This task is used to convert a lead into a contact, deal, and account in Zoho CRM. During lead conversion, Zoho CRM creates new Contact and Account records by default. If an existing contact or account ID is provided in the request, the lead will be linked to the specified existing record instead of creating a new one. To convert a lead into a deal, the Deals module must be specified, and its mandatory fields must be mapped to their corresponding values in the script.

Syntax

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

where,

ParameterData typeDescription
<variable>KEY-VALUEHolds the response returned by Zoho CRM on successful task execution or error details on failure. Here 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 retrieve the unique record ID from the response returned by Zoho CRM 
after creating, searching, or fetching a record.

<values>

 

(Optional)

KEY-VALUE

Specifies the conversion options and related record details (such as account, contact, or deal information) to be applied when converting a lead. Refer to Zoho CRM API for more details.

Each module in Zoho CRM contains mandatory fields that are required to create a record. Refer to this page for the list of mandatory fields in each module.

<connection>TEXT

Represents the link name of the connection which is connected to your Zoho CRM account.

Note:

Examples

1. Create new record in Contacts, Deals, and Accounts module

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

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

where,

response
is the variable that holds the response returned by Zoho CRM. Here it represents the IDs of the new records created in Contacts, Deals, and Accounts modules.
2303XXXXXXXXXXXXXXX
is the NUMBER that represents the ID of the lead that needs to be converted.
"Deals"
is the key parameter which holds the values of the new record to be created in the Deals Module.
deal_values
is the KEY-VALUE variable that holds the 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. These are mandatory to convert a lead into a deal.

Here, the account and contact are created by default, and a deal is created as the Deals key is provided in the <values> map along with the mandatory fields: Deal_Name, Closing_Date, and Stage.

2. Associate the converting lead to an existing account and contact

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 = Collection();
values_map.insert("overwrite":true);
values_map.insert("Accounts":"2303XXXXXXXXXXXXXXX");
values_map.insert("Contacts":"2303XXXXXXXXXXXXXXX");
response = zoho.crm.v8.convertLead(2303XXXXXXXXXXXXXXX,values_map);

where,

values_map
is the KEY-VALUE variable that holds the IDs of the existing record from Accounts and Contacts modules.

Note: Refer this page 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 are not provided is of the following format:
{
 "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 already been converted is of the following format:
{
 "code":"ID_ALREADY_CONVERTED",
 "details":{},
 "message":"id already converted",
 "status":"error"
}