Convert Lead

Purpose

To convert a lead into a contact or an account.

Request Details

Request URL

{api-domain}/crm/{version}/Leads/{record_id}/actions/convert

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.modules.ALL
(or)
scope=ZohoCRM.modules.leads.{operation_type}

Possible operation types

ALL - Full access to the record
WRITE - Edit records in the module
CREATE - Create records in the module

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2.1/Leads/554023000001053012/actions/convert"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@convertlead.json"
-X POST
4.0.04.x
Copied//Get instance of RecordOperations Class
$recordOperations = new RecordOperations();
//Get instance of ConvertBodyWrapper Class that will contain the request body
$request = new ConvertBodyWrapper();
//List of LeadConverter instances
$data = array();
//Get instance of LeadConverter Class
$record1 = new LeadConverter();
$record1->setOverwrite(true);
$record1->setNotifyLeadOwner(true);
$record1->setNotifyNewEntityOwner(true);
$record1->setAccounts("34770615848125");
$record1->setContacts("34770610358009");
$record1->setAssignTo("34770610173021");
$recordClass = 'com\zoho\crm\api\record\Record';
$deals = new $recordClass();
/*
 * Call addFieldValue method that takes two arguments
 * 1 -> Call Field "." and choose the module from the displayed list and press "." and choose the field name from the displayed list.
 * 2 -> Value
 */
$deals->addFieldValue(Deals::DealName(), "deal_name");
$deals->addFieldValue(Deals::Description(), "deals description");
$deals->addFieldValue(Deals::ClosingDate(), new \DateTime("2021-06-02"));
$deals->addFieldValue(Deals::Stage(), new Choice("Closed Won"));
$deals->addFieldValue(Deals::Amount(), 50.7);
$deals->addKeyValue("Pipeline", new Choice("Qualification"));
/*
 * Call addKeyValue method that takes two arguments
 * 1 -> A string that is the Field's API Name
 * 2 -> Value
 */
$deals->addKeyValue("Custom_field", "Value");
$deals->addKeyValue("Custom_field_2", "value");
$record1->setDeals($deals);
$carryOverTags = new CarryOverTags();
$carryOverTags->setAccounts(["Test"]);
$carryOverTags->setContacts(["Test"]);
$carryOverTags->setDeals(["Test"]);
$record1->setCarryOverTags($carryOverTags);
//Add Record instance to the list
array_push($data, $record1);
//Set the list to Records in BodyWrapper instance
$request->setData($data);
//Call updateRecord method that takes BodyWrapper instance, ModuleAPIName and recordId as parameter.
$response = $recordOperations->convertLead($recordId,$request );
Copied<?php

class ConvertLead
{
    public function execute(){
        $curl_pointer = curl_init();
        
        $curl_options = array();
        $url = "https://www.zohoapis.com/crm/v2.1/Leads/3525811001/actions/convert";
        
        $curl_options[CURLOPT_URL] =$url;
        $curl_options[CURLOPT_RETURNTRANSFER] = true;
        $curl_options[CURLOPT_HEADER] = 1;
        $curl_options[CURLOPT_CUSTOMREQUEST] = "POST";
        $requestBody = array();
        $recordArray = array();
        $recordObject = array();
        $recordObject["overwrite"]=true;
        $recordObject["notify_lead_owner"]=true;
        $recordObject["Accounts"]="3524033000005113002";
        $recordObject["notify_new_entity_owner"]=true;
        $recordObject["Contacts"]="3524033000003661075";
        
        $recordArray[] = $recordObject;
        $requestBody["data"] =$recordArray;
        $curl_options[CURLOPT_POSTFIELDS]= json_encode($requestBody);
        $headersArray = array();
        
        $headersArray[] = "Authorization". ":" . "Zoho-oauthtoken " ."1000.30f3a589XXXXXXXXXXXXXXXXXXX4077.dc5XXXXXXXXXXXXXXXXXXXee9e7c171c";
        
        $curl_options[CURLOPT_HTTPHEADER]=$headersArray;
        
        curl_setopt_array($curl_pointer, $curl_options);
        
        $result = curl_exec($curl_pointer);
        $responseInfo = curl_getinfo($curl_pointer);
        curl_close($curl_pointer);
        list ($headers, $content) = explode("\r\n\r\n", $result, 2);
        if(strpos($headers," 100 Continue")!==false){
            list( $headers, $content) = explode( "\r\n\r\n", $content , 2);
        }
        $headerArray = (explode("\r\n", $headers, 50));
        $headerMap = array();
        foreach ($headerArray as $key) {
            if (strpos($key, ":") != false) {
                $firstHalf = substr($key, 0, strpos($key, ":"));
                $secondHalf = substr($key, strpos($key, ":") + 1);
                $headerMap[$firstHalf] = trim($secondHalf);
            }
        }
        $jsonResponse = json_decode($content, true);
        if ($jsonResponse == null && $responseInfo['http_code'] != 204) {
            list ($headers, $content) = explode("\r\n\r\n", $content, 2);
            $jsonResponse = json_decode($content, true);
        }
        var_dump($headerMap);
        var_dump($jsonResponse);
        var_dump($responseInfo['http_code']);
        
    }
    
}
(new ConvertLead())->execute();
2.1.0
Copied# """
records = []
module_api_name = 'Leads'
(0..0).each do |i|
  # Get instance of LeadConverter Class
  record = Record::LeadConverter.new
  #set overwrite
  record.overwrite = true
  #set notify lead owner
  record.notify_lead_owner = true
  #set notify entity lead owner
  record.notify_new_entity_owner = true
  #set accounts
  record.accounts = '3524033000005113002'
  #set contacts
  record.contacts = '3524033000003429023'
  #set assign to
  record.assign_to = '3524033000003523022'
  Date.new(2001, 2, 3)
  #get instance of deals record
  deals = Record::Record.new
  # """
  # Call add_field_value method that takes two arguments
  # 1 -> Call Field "::" and choose the module from the displayed list and press "." and choose the field name from the displayed list.
  # 2 -> Value
  # """
  deals.add_field_value(Record::Field::Deals.Closing_date, DateTime.new(2019, 8, 10, 4, 10, 9))
  deals.add_field_value(Record::Field::Deals.Deal_name, 'deal_name')
  deals.add_field_value(Record::Field::Deals.Description, 'deal_name')
  deals.add_field_value(Record::Field::Deals.Stage, Util::Choice.new('Closed Won'))
  deals.add_field_value(Record::Field::Deals.Amount, 50.7)
  # """
  # Call add_key_value method that takes two arguments
  # 1 -> A string that is the Field's API Name
  # 2 -> Value
  # """

  deals.add_key_value('Custom_field', 'Value')
  deals.add_key_value('Custom_field_2', 'value')
  # deals.add_key_value("Closing_Date","2020-08-11T14:21:15+05:30")
  record.deals = deals
  records.push(record)
end
# Get instance of ConvertBodyWrapper Class that will contain the request body
convert_body_wrapper = Record::ConvertBodyWrapper.new
#set records to data
convert_body_wrapper.data = records
# Get instance of RecordOperations Class
rr = Record::RecordOperations.new
# Call convertLead method that takes ConvertBodyWrapper instance and lead_id as parameter
response = rr.convert_lead(lead_id,convert_body_wrapper)
Copiedrequire 'net/http'
require 'json'

class ConvertLead
    def execute
       
        url ="https://www.zohoapis.com/crm/v2.1/Leads/3524033000005811001/actions/convert"
        url = URI(url)
        req = Net::HTTP::Post.new(url.request_uri)
        http = Net::HTTP.new(url.host, url.port)
        http.use_ssl = true
        headers={}
        headers["Authorization"]="Zoho-oauthtoken 1000.dfa7XXXXXXXXXXXXXXXXXX84f9665840.c176aeXXXXXXXXXXXX13f3d37a84d"
        headers&.each { |key, value| req.add_field(key, value) }
       
        request_body = {};
        record_array = [];
        record_object = {};
        record_object["overwrite"]=true;
        record_object["notify_lead_owner"]=true;
        record_object["Accounts"]="3524033000005113002";
        record_object["notify_new_entity_owner"]=true;
        record_object["Contacts"]="3524033000003661075";  
        record_array = [record_object];
        request_body["data"] =record_array; 
        request_json = request_body.to_json
        req.body = request_json.to_s
        response=http.request(req)
        status_code = response.code.to_i
        headers = response.each_header.to_h
        print status_code
        print headers
        unless response.body.nil?
            print  response.body
        end
    end
end

ConvertLead.new.execute

In the request, "@convertlead.json" contains the sample input.

Input JSON Keys

To convert leads, send a POST request with request body containing the following attributes:

  • overwriteboolean, optional

    Specify if the Lead details must be overwritten in the Contact/Account/Deal based on lead conversion mapping configuration.
    true: Overwrite the lead details in Contact/Account/Deal. Note that when this value is true and you have specified an account ID, only the account name will be overwritten with the company name of that contact. Rest of the details are unchanged.
    false: Do not overwrite the lead details to Contact/Account/Deal.

  • notify_lead_ownerboolean, optional

    Specify whether the lead owner must get notified about the lead conversion via email.
    true: The lead owner gets notified about the conversion via email.
    false: The lead owner does not get notified about the conversion via email. The default value is false.

  • notify_new_entity_ownerboolean, optional

    Specify whether the user to whom the contact/account is assigned to must get notified about the lead conversion via email.
    true: The user gets notified about the conversion via email.
    false: The user does not get notified about the conversion via email. The default value is false.

  • Accountsstring, optional

    Use this key to associate an account with the lead being converted. Pass the unique and valid account ID.
    Example: "Accounts": "4000000373187"

  • Contactsstring, optional

    Use this key to associate a contact with the lead being converted. Pass the unique and valid contact ID.
    Example: "Contacts": "4000000372131"

  • Contact_RoleString, optional

    Use this key to assign a role to the contact that you have associated on conversion. Make a GET Contact Roles API call and pass the unique contact role ID.

  • assign_tostring, optional

    Use this key to assign record owner for the new contact and account. Pass the unique and valid user ID.
    Example: "assign_to": "4000000219019"

  • DealsJSON object, optional

    Use this key to create a deal for the newly created Account. The "Deal_Name", "Closing_Date", "Pipeline", and "Stage" are default mandatory keys to be passed in the JSON object.

  • carry_over_tagsJSON object, optional

    Use this key to carry over tags of the lead to contact, account, and deal. Refer to sample input for format.

Note

  • In the input, the assign_to value can only be the User ID.
  • You can associate the existing contact or account to the converting lead even if the lead is converted or not converted to a deal. To achieve this, you have to send the account ID and contact ID in your input data.
  • If both account ID and overwrite values are true, then the account name will be replaced by the company name, while associating it with the existing account. However, the data of that account will remain the same.
  • If overwrite value is set to false, then association will only happen. However, if you set the overwrite value without account ID, the working of this method remains unchanged.
  • If contact ID is given in your input, then the converting lead will be associated to the existing contact.
  • You must use only Field API names in the input. You can obtain the field API names from
    • Fields metadata API (the value for the key “api_name” for every field). (Or)
    • Setup > Developer Hub > APIs and SDKs > API Names > {{Module}}. Choose “Fields” from the “Filter By” drop-down.

Sample Input

Copied{
    "data": [
        {
            "overwrite": true,
            "notify_lead_owner": true,
            "notify_new_entity_owner": true,
            "Accounts": "4150868000003283003",
            "Contacts": "4150868000003283024",
            "assign_to": "4150868000001248015",
            "Deals": {
                "Deal_Name": "Robert",
                "Closing_Date": "2020-07-24",
                "Stage": "Closed Won",
                "Amount": 5000,
                "Pipeline":"Standard (Standard)",
                "Contact_Role": "5545974000000006873"
            },
            "carry_over_tags": {
                "Contacts": [
                    "tag1",
                    "tag2"
                ],
                "Accounts": [
                    "tag1"
                ],
                "Deals": [
                    "tag1"
                ]
            }
        }
    ]
}

Possible Errors

  • DUPLICATE_DATAHTTP 400

    Duplicate data
    Resolution: There already exists a contact with the unique field details present in lead. Ensure you specify unique values for unique fields (both system and user-defined). To know which fields are unique, refer to Fields Metadata API.

  • ID_ALREADY_CONVERTEDHTTP 202

    id already converted
    Resolution: The lead you are trying to convert has already been converted. Specify a valid lead ID. Refer to Get Records API to get valid lead IDs.

  • INVALID_URL_PATTERNHTTP 404

    Please check if the URL trying to access is a correct one
    Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to request URL section above.

  • OAUTH_SCOPE_MISMATCHHTTP 401

    Unauthorized
    Resolution: Client does not have ZohoCRM.modules.{module_name}.CREATE. Create a new client with valid scope. Refer to scope section above.

  • NO_PERMISSIONHTTP 403

    Permission denied to create
    Resolution: The user does not have permission to create records. Contact your system administrator.

  • INTERNAL_ERRORHTTP 500

    Internal Server Error
    Resolution: Unexpected and unhandled exception in the server. Contact support team.

  • INVALID_REQUEST_METHODHTTP 400

    The http request method type is not a valid one
    Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to endpoints section above.

  • AUTHORIZATION_FAILEDHTTP 400

    User does not have sufficient privilege to create records
    Resolution: The user does not have the permission to create records. Contact your system administrator.

  • INVALID_DATAHTTP 400

    invalid data
    Resolution: The input specified is incorrect. Specify valid input.

  • RECORD_LOCKEDHTTP 400

    cannot convert record that is not approved yet
    Resolution: Please wait until the Zia image or the merge duplicates process is complete and try again.

  • NOT_APPROVEDHTTP 400

    cannot convert record that is not approved yet
    Resolution:

    • Case 1: If the record is in the rejected state due to Zia image validation, either upload a new image (or) delete the failed image and, resubmit the record to Zia image validation.
    • Case 2: If the record is in Zia record approval, the system will not allow you to update the images of the record until the reviewer approves or rejects the record.

Sample Response

Copied{
    "data": [
       {
            "Contacts": "4000000372131",
            "Deals": "4000000377192",
            "Accounts": "4000000373187"
        }
    ]
}