convertLead Method

Table of Contentsup

 Purpose

You can use this method to convert lead to potential, account and contact. You can also associate the existing contact or account to the converting lead using this method.

For lead conversion process, see Convert Leads to Other Sales Records  in User Manual.

 Request URL

XML Format:
https://<APPDOMAIN>/crm/private/xml/Leads/convertLead?leadId=entity Id&xmlData=POTENTIALXMLDATA

JSON Format:
https://<APPDOMAIN>/crm/private/json/Leads/convertLead?leadId=entity Id&xmlData=POTENTIALXMLDATA

 Auth Token

Auth Token is an encrypted alphanumeric string that is required to authenticate your CRM account credentials. A valid user's Authentication Token is necessary to access the API. When making an API request, send the authentication token in the Authorization header as shown below:

https://<APPDOMAIN>/crm/private/xml/Leads/convertLead?leadId=entity Id&xmlData=POTENTIALXMLDATA

Header:

Authorization=1000XXXX65.1000XXXX44.caXXXXXXXXXXXX

(See Using Authentication Token )

 Request Parameters

ParameterData TypeDescription
authtoken*StringEncrypted alphanumeric string to authenticate your Zoho credentials.
scope*StringSpecify the value as crmapi
leadId*StringSpecify unique ID of the lead
xmlData*XMLSpecify fields and corresponding values
newFormatIntegernewFormat=1: To exclude fields with "null" values while inserting data from your CRM account.
newFormat=2:To include fields with "null" values while inserting data from your CRM account.
versionIntegerversion = 1: (Default value) This will fetch responses based on the earlier API implementation i.e prior to the enhancements made.
version = 2: This will fetch responses based on the latest API implementation.

* - Mandatory parameter

Note:

  • Refer the Release Notes  page to learn more about enhancements made in the API implementation.

 Sample XML to convert a Lead into an Account, Contact and Potential

<Potentials>
<row no="1">
<option val="createPotential">true</option>
<option val="assignTo">sample@zoho.com</option>
<option val="notifyLeadOwner">true</option>
<option val="notifyNewEntityOwner">true</option>
</row>
<row no="2">
<FL val="Potential Name">Samplepotential</FL>
<FL val="Closing Date">12/21/2009</FL><FL val="Potential Stage">Closed Won</FL>
<FL val="Contact Role">Purchasing</FL>
<FL val="Amount">3432.23</FL>
<FL val="Probability">100</FL>
</row>
</Potentials>

Note:

  • In this XML, <row no="2"> is mandatory ONLY if the value for "createPotential" is set to true. If the value for "createPotential" is set to false, a Potential will NOT be created on conversion of the Lead.

 Sample XML to associate the existing contact or account to the converting lead

<Potentials>
<row no="1">
<option val="createPotential">true</option>
<option val="assignTo">sample@zoho.com</option>
<option val="notifyLeadOwner">true</option>
<option val="notifyNewEntityOwner">true</option>
</row>
<row no="2">
<FL val="Potential Name">Samplepotential</FL>
<FL val="Closing Date">12/21/2009</FL><FL val="Potential Stage">Closed Won</FL>
<FL val="Contact Role">Purchasing</FL>
<FL val="Amount">3432.23</FL>
<FL val="Probability">100</FL>
<FL val="ACCOUNTID">543212345</FL>
<FL val="CONTACTID">1234554321</FL>
<FL val="OVERWRITE">true</FL>
</row>
</Potentials>

Note:

  • The assignTo value can either be SMOWNERID or email id.
  • You can associate the existing contact or account to the converting lead even if the lead is converted or not converted to a potential. To achieve this, you have to send ACCOUNTID and CONTACTID through xml
  • If both <FL val="ACCOUNTID"></FL> and <FL val="OVERWRITE">true</FL> values are given, then the account name will be replaced by the company name while associating with the existing account. However, the data of that account will remain the same
  • If OVERWRITE value is false, then association will only happen. However, if you give OVERWRITE value without giving ACCOUNTID, the working of this method remains unchanged
  • If <FL val="CONTACTID"></FL> is given, then the converting lead will be associated to the existing contact

 Sample XML to convert a Lead without creating a Potential

<Potentials>
<row no="1">
<option val="createPotential">false</option>
<option val="assignTo">sample@zoho.com</option>
<option val="notifyLeadOwner">true</option>
<option val="notifyNewEntityOwner">true</option>
</row>
</Potentials>