Convert Lead
Purpose
To convert a lead into a contact or an account, use the Lead Conversion Options API to identify existing records in Contacts, Accounts, and Deals that match the lead's data before conversion.
This helps prevent duplicate records by allowing you to associate the lead with existing records instead of creating new ones with the same data.
Endpoints
- POST /Leads/{record_id}/actions/convert
{record_id} : The unique ID of the Lead record you want to convert.
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.CREATE
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v8/Leads/3652397000007566544/actions/convert"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@convertlead.json"
-X POSTIn the request, "@convertlead.json" contains the sample input.
Order of preference for mapping with Contacts and Accounts
- No Unique Fields in the Leads Module
- The email ID of the lead is checked against email IDs in the Contacts module.
- The Company of the lead is checked against account names in the Accounts module.
- The lead's name is checked against names in the Contacts module.
- Presence of Unique Fields
- The order of preference is Contacts module first, followed by the Accounts module, based on field mapping and layout mapping.
- If there is no unique field in the Contacts module but a unique field exists in the Accounts module, then the order of preference will be Accounts first, followed by Contacts.
- Mapping Criteria
- Contacts: Unique field 1, Unique field 2, or Email (if Email is unique).
- Accounts: Unique field 1 or Unique field 2.
Input JSON Keys
- overwriteboolean, optional
Determines whether to overwrite the Account Name in a Contact when converting a Lead.
For example, If a Contact is already linked to an Account but the Lead’s Company name is different, enabling this option will update the Contact’s Account to match the Lead’s Company.Possible values:
- false (default) : Keeps the existing Account Name in the Contact unchanged.
- true : Updates the Contact’s associated Account Name if it differs from the Company name in the Lead.
- notify_lead_ownerboolean, optional
Specifies whether the Lead Owner should receive an email notification when the lead is converted.
Possible values:- false (default) : No email notification is sent.
- true : Sends an email notification to the lead owner upon conversion.
- move_attachments_toJSON object, optional
Specifies the API name of the module (Contacts, Deals, or Accounts) where the attachments from the lead should be moved upon conversion. It ensures that important files and documents attached to the lead are transferred to the appropriate module after conversion.
Possible values:
- Contacts : Move attachments to the associated Contact.
- Deals : Move attachments to the associated Deal.
- Accounts : Move attachments to the associated Account.
- AccountsJSON object, optional
It associates a lead to an existing Account instead of creating a new one during conversion. It helps maintain data consistency by associating the lead with an existing account instead of creating a duplicate. Use the GET - Records API to retrieve unique Account IDs.
- ContactsJSON object, optional
Associates a lead with an existing contact instead of creating a new one during conversion. It helps maintain data consistency by linking the lead to an existing contact, avoiding duplicate contact creation. Use the GET - Records API to retrieve unique Contacts IDs.
- assign_toJSON object, optional
Assigns a record owner for the new Contact and Account after lead conversion. It ensures that the converted lead is assigned to a specific user in Zoho CRM. Use the GET - Users API to retrieve valid User IDs.
- DealsJSON object, optional
Use this key to create a deal for the newly created Account during lead conversion.
Mandatory fields required to create a deal for the newly converted record:
- Deal_Name : API name of the deal.
- Closing_Date : Expected closing date of the deal.
- Pipeline : The sales pipeline the deal belongs to.
- Stage : The current stage of the deal in the pipeline.
The "Contact_Role" key lets you 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.
- carry_over_tagsJSON object, optional
Use this key to carry over tags from the lead to the newly created contact, account, and deal during lead conversion.
Note
- Use the Lead Conversion Options API to get the records that have matching data with the lead you want to convert in Contacts, Accounts, and Deals. This enables you to convert a lead and associate it with the relevant records instead of creating new ones with the same data.
- In the input, the assign_to value can only be the User ID.
- If the lead is not converted to a deal, it will still get associated to the contact and account you specified in the input.
- 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.
- 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 go to 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,
"move_attachments_to": {
"api_name": "Deals"
},
"Accounts": {
"id": "3652397000000624046"
},
"Contacts": {
"id": "3652397000000624640"
},
"Deals": {
"Deal_Name": "test",
"Closing_Date": "2020-10-20",
"Stage": "Negotiation/Review",
"Amount": 20000000,
"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 400
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: You do not have the right scope to access this API. Create a new client with the valid scope mentioned in the "Scope" section. - 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. - RECORD_LOCKEDHTTP 400
You cannot perform this operation as the record is locked.
Resolution: Please wait until the record is unlocked. - 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": [
{
"code": "SUCCESS",
"details": {
"Contacts": {
"name": "Paul Daly",
"id": "3652397000007603014"
},
"Deals": {
"name": "test",
"id": "3652397000007603019"
},
"Accounts": {
"name": "Zylker",
"id": "3652397000000624046"
}
},
"message": "The record has been converted successfully",
"status": "success"
}
]
}