Changelogs

API Domain

For V2.1 and above versions, you must use the dedicated domain name to make API calls. The default domain is: https://www.zohoapis.com/ (US)
This is helpful in serving CORS requests. The other supported domains are:

• Europe - https://www.zohoapis.eu/
• China - https://www.zohoapis.com.cn/
• India - https://www.zohoapis.in/

For more information, refer to Multi DC Support. If you fire API calls with a domain other than https://www.zohoapis.{dc}, the system will throw INVALID_HOST error with HTTP status 400.

Version V2.1

The Zoho CRM APIs with updates that apply to the V2.1 version are listed below.

The changes in each of the Zoho CRM APIs are explained below:

1. Modules API

   1a. Updates in the existing key values and their data types

   (i) "module_name" key: The value of "module_name" key is now Meetings.

   

   (ii) "generated_type" key: The value for the "generated_type" for multi-select user lookup fields in the linking module, and line item subform will be linking and subform, respectively.

   The following responses illustrate the linking module generated by the system for a multi-select user lookup in the Accounts module and subform.

   
   

   Similarly, when Enable history tracking for picklist values option is enabled for a picklist, the value of generated_type key will be picklisttracker.

   

   (iii) "custom_view" key: The changes in the custom view key of get specific module metadata API are illustrated in detail in the Custom View Metadata API section.

   1b. Other changes

   • Filter based on profile permission: The details of all the modules will be fetched in the response irrespective of the user profile permissions.
   • The modules that are removed from Organize modules will also be fetched.

2. Fields and Layouts Metadata API

   2a. Keys introduced in V2.1

   

   • typestring

     A new key that represents the type of the field or layout is introduced from V2.1. The possible values are:
     used: the field is present in one or more layouts in a module
     unused: the field is removed from all the layouts in a module

   • profilesJSON array

     A new JSON array profiles is introduced in the response that gives details of the profiles that the field is visible to. For users with profile without the Module Customization permission, the value for this key holds null.

   • display_typeinteger

     Represents how the field is displayed based on its type.

     • -1: Normal field
     • 0- Removed field
     • 1 - Hidden field
     • 2 - Select only field; for instance, Best time to contact
     • 3 - Hidden and select only field
     • 4 - Criteria only field
     • 5 - Hidden and criteria only field
   • pick_list_values_sorted_lexicallyboolean

     Represents whether the values of the picklist are sorted alphabetically.

     • true: The picklist values are sorted alphabetically
     • false: The picklist values are not sorted alphabetically
   • sortableboolean

     Represents whether the field is sortable.

     • true: You can sort records based on this field's value
     • false: You cannot sort records based on this field's value
   • wizardboolean

     When you create a wizard for a module, a the system creates a new field with api_name Wizard of data_type bigint.

   • Quoted_ItemsJSON array

     In the inventory modules, the "Product_Details" section is replaced with a subform based on the inventory module. For the Quotes module, "Product_Details" JSON array is replaced with "Quoted_Items".

   • Invoiced_ItemsJSON array

     In the inventory modules, the "Product_Details" section is replaced with a subform based on the inventory module. For the Invoices module, "Product_Details" JSON array is replaced with "Invoiced_Items".

   • Purchase_ItemsJSON array

     In the inventory modules, the "Product_Details" section is replaced with a subform based on the inventory module. For the Purchase Orders module, "Product_Details" JSON array is replaced with "Purchase_Items".

   • Ordered_ItemsJSON array

     In the inventory modules, the "Product_Details" section is replaced with a subform based on the inventory module. For the Sales Orders module, "Product_Details" JSON array is replaced with "Ordered_Items".

   • multiselectlookupJSON object

     A new key that represents the details such as linking module, connected module, lookup API name etc, of a multi-select lookup field. The JSON object represents the following details of the multi-select lookup field:

     • display_label: The display of the related list. For instance, if there is a multi-select lookup for Products(m) in the Contacts(n) module, this key entails the display of the products related list in the Contacts module for this respective m_x_n field.
     • linking_module: The API name of the linking module (system-generated)
     • lookup_apiname: The API name of the lookup field in the linking module. For instance, if there is a multi-select lookup for Products(m) in the Contacts(n) module, the lookup_apiname is the API name of the contacts field in the linking module(m_X_n).
     • connected_module: The API name of the lookup module. For instance, if there is a multi-select lookup for Products in the Contacts module, the connected_module will be Products.
     • api_name: The API name of the related list. For instance, if there is a multi-select lookup for Products(m) in the Contacts(n) module, this key entails the display of the products related list in the Contacts module for this respective m_x_n field.
     • connectedlookup_apiname: The API name of the connected lookup field in the linking module. For instance, if there is a multi-select lookup for Products(m) in the Contacts(n) module, the connectedlookup_apiname is the API name of the products field in the linking module(m_X_n).
     • id: The unique ID of the relation between the two modules that are related through the multiselect lookup.
     
   • multiuserlookupJSON object

     A new key that represents the details of the multi-user lookup field is introduced from V2.1.

     

   2b. Updates in the existing key values and their data types

   • Update in the data type of the "history_tracking" key: The data type of the history_tracking key is now JSON object. The key represents the history of the picklist field if you have enabled history tracking. The value null represents that history tracking is not enabled for the field.

   • picklist: Represents the list of all the picklist values, if the field is either a picklist or multi-select picklist field. From V2.1, each object in the "pick_list_values array" entails the unique ID and the type of the picklist value. The value for the key type in each picklist option represents if that option is used or not. The response contains both used and unused picklist values.

     

   • data_type: For multi-user lookup fields, the data_type is multiuserlookup. Similarly, for image upload fields, the data_type is imageupload.

     

   2c. Parameters introduced in V2.1

   type: The value unused fetches all the unused fields and all fetches all both used and unused fields in the module. By default, the system fetches all the used fields.

   2d. Module-wise changes in the fields metadata API

   • Deals: When a pipeline is in place, the Deals module will have the pipeline key. In Layouts Metadata API response, along with the picklist values, a key named maps of type JSON array will also be fetched.

     

   • Leads: A new field called Lead_Conversion_Time of the type integer is introduced in the Leads module.

     
   • Users:

     • A new field Reporting_To is added representing the details of the users that the current user is reporting to.

       

     • The Time_Zone field will incorporate daylight savings.

       
     • If translation is enabled, the display_value of a picklist will show the values in the translated language.
   • Products:

     • From V2.1, in the Tax field, the unique ID and type of each tax type is added in pick_list_values JSON array.

       
   • Calls:
     • From V2.1, two additional fields are added to the Calls module: Outgoing_Call_Status, Scheduled_In_CRM. The metadata of these fields is retrieved in the fields metadata response.

   2e. Other Changes

   • Filter based on field permission: All the fields will be fetched in the fields metadata response irrespective of the field permissions. You can identify if a field is visible to the current user in UI, using the value in the "visible" key. The value true indicates that the field is visible to the current user.

   2f. Keys introduced in V2.1 specific to Layouts Metadata API

   
   • _default_viewJSON object

     The key is added to the layouts metadata response from V2.1. It represents the unique ID, name, and type of the default view for each profile in the profiles JSON array.

   • show_business_cardboolean

     Represents if the business card section is visible in the layout or not. The possible values are:
     true: the business card section is visible in the layout
     false: the business card section is not visible in the layout

   • typestring

     Represents if a section is used or not. The possible values are: used and unused.

3. Insert and Update Records API

   3a. Keys introduced in V2.1

   The keys listed below will be retrieved in the Get Records API response from V2.1.

   • Image_UploadJSON array

     From V2.1, you can add/update images to the image upload fields using this key. Each object in the array represents the unique ID of the image file.

     

     Also, you can delete images from the image upload fields using the _delete key.

     
   • File_UploadJSON array

     From V2.1, you can add/update files to the file upload fields using this key. Each object in the array represents the unique ID of the file.

     
   • Multi-select LookupJSON array

     In v2, you cannot add details to the multi-select lookup field directly. You have to obtain the API name of the linking module through Modules API, and then add records to that module. This procedure has been simplified in V2.1. Here, you can directly add values to the multi-select lookup fields while adding the parent record itself.

     
   • Multi-user lookupJSON array

     From V2.1, you can add/update the multi-user field through API. Each object in the array represents the unique ID of the user to be mapped.

     
   • pipelineString

     From V2.1, you can assign records to a Pipeline. Note that this key is mandatory when pipeline is enabled for the Deals module. Also, it is mandatory to input the Stage for the deal record. Use the Get Pipelines API to get the name of the pipeline. You can also retrieve the details of the pipeline field through Fields and Layouts metadata API.

     
   • lar_idString

     From V2.1, you can trigger a lead assignment rule by specifying this key in the request input. Use the Get Assignment Rules API to obtain the lar_id. This key must be given parallel to the key "data".

     
   • wizardJSON object

     From V2.1, you can add wizards to records by specifying this key. Refer to Get Wizards API for more details.

     

   Refer to Insert records API for the sample code.

   3b. Module-wise changes in the Insert Records API

   In the inventory modules, the "Product_Details" section is replaced with a subform based on the inventory module. Here is a glimpse of how this section looks in the input. The following table lists the equivalent of the "Product_Details" in the inventory modules.

   Inventory module	Equivalent of "Product_Details" key in V2.1
   Quotes	Quoted_Items
   Invoices	Invoiced_Items
   Purchase Orders	Purchase_Items
   Sales Orders	Ordered_Items

   

   The following table lists the JSON keys in v2 and their equivalent in V2.1.

   V2	V2.1
   Product_Details JSON array	Quoted_Items JSON array
   product JSON object	Product_Name JSON object
   quantity Integer	Quantity Integer
   total_after_discount Integer	Total_After_Discount Integer
   net_total Integer	Net_Total Integer
   book JSON object	Price_Book_Name JSON object
   list_price Integer	List_Price Integer
   total Integer	Total Integer
   product_description String	Description String
   line_tax JSON array	Line_Tax JSON array

   3c. Other Changes

   

   From V2.1, all records enter the review process by default. The support to add "review_process" key in the request input has been removed.

4. Get Records API

   4a. Keys introduced in V2.1

   • $has_moreboolean

     The key represents if there are more records mapped in multi-select/multi-user lookup fields.

     
   • $sharing_permissionstring

     Represents the sharing permission of the current user

     

   4b. Updates in existing keys and their data types

   • multi-select lookup key: From V2.1, the data type of this key is JSON array. Each object in the array represents the name, unique ID and the lookup of the multi-select lookup record.

   • Product_Details key: From V2.1, the system will not return product details in the get records response for inventory modules. It can be retrieved only through get specific record API.

     

   • Tax key: From V2.1, the system will return the unique ID of the tax along with the product details.

     

   • Territories key: From V2.1, the data type of the territories key is array of objects instead of JSON array. Each object in the array represents the details of the territory.

     

   4c. Module specific updates

   • Calls API

     
     • Outgoing_Call_Statusstring

       Represents the status of the outgoing call

     • Scheduled_In_CRMBoolean

       Represents if the call was scheduled in Zoho CRM

   • Events API

     
     • $event_cancelledboolean

       Represents if the event is canceled or not

5. Convert Lead API

   If you have enabled pipeline, you can include the pipeline's details while converting a lead to a deal. Refer to Convert Lead API for sample code.

6. Get and Update Blueprints API

   6a. Keys introduced in V2.1

   • multi-select lookupJSON array

     You can now include multi-select lookup details directly in the request input.

   • multi-user lookupJSON array

     From V2.1, you can include multi-user lookup details directly in the request input.

   • widgetJSON object

     You can now include widgets directly in the request input.

   • escalationJSON object

     When a transition is set to automatic, you can choose the time period that a record can stay in a particular state before moving to the next. This time period is defined in the escalation key under process_info. The value for "escalation" will be null for manual transitions.

   • execution_timestring

     From V2.1, execution_time key is introduced in the response. The value for this key is null for manual transitions, and date/time for automatic transitions.

   • typeString

     Represents the type of transition.

   

   6b. Updates in existing keys and their data types

   • $link_urlstring

     From V2.1, the data type of the $link_url key is string instead of JSON array. Each link attachment must be specified in a JSON object with link attachment name and URL in "name" and "$link_url" keys respectively.

     
   • $attachTeamDriveDocIdsstring

     From V2.1, you can add attachments from team drive.

   • $attachDocsstring

     From V2.1, you can add attachments from Documents uploaded in your organization.

   • $attachZDocsstring

     From V2.1, you can add attachments from documents from Zoho Docs.

   • $attachGDocsstring

     From V2.1, you can add attachments from documents from Google Docs.

   • criteria_matchedboolean

     From V2.1, the criteria_matched key is introduced to the "next_transitions" array. It represents whether the record matches the entry criteria for upcoming transitions. Also, from V2.1, only the transitions that are accessible to the current user are retrieved.

     
   • user lookupJSON object

     From V2.1, the data type of the user lookup field is JSON object instead of string. The JSON object represents the name and unique ID of the user.

   • module idstring

     From V2.1, the data type of the unique ID of the module in the "module" JSON object is string instead of long.

7. Add and Remove Tags from records API

   • Change in response structure

     The response structure has changed for the add and remove tags from a record APIs. The response includes the names and the IDs of the tags that are added or removed.

     

8. Get Shared Record Details API

   • "manage" parameter is not available from V2.1

     The Get Shared Record's Details API does not support the parameter view=manage.

     

   • Changes in response based on usecase

     From V2.1, the response differs based on the access permission of the user on the shared record. For instance, if User A shares a record with User B, the response differs based on the record access permission of User B.

     

     (i) If User B already has full permission access over the shared record via role, territory, data sharing, user-lookup field, the response will entail the "user" key representing the all the users with whom the record is shared.

     (ii) If User B gains access to the record only via record-level sharing, response retrieved has the details of user's own sharing details of the record. The response will not entail details of the other users with whom the record is shared.

9. POST Share Record API

   • If you specify an invalid data for the permission key, the status code for the INVALID_DATA error 200 OK has been changed to 400 Bad Request.

10. Bulk Read API

    9a. Updates in the existing keys in create bulk read job API

    • The data type of the key module is changed from string to JSON object. It includes the key api_name to represent the module's name to bulk fetch the records from.

    • The structure of the criteria key is changed. We have included the JSON object field, that takes the API name of the field based on whose value you want to filter the records.

      

    9b. Updates in the existing keys in get bulk read job details

    The download_url will display the version number as v2.1 instead of v2.

    

11. Bulk Write API

    • Similar to the Bulk Read API, we have changed the module key's datatype from string to JSON object with the api_name key.

      
    • In the response, under the resource JSON array, we have a new key called code.

    • The module key is now a JSON object instead of a string.

      

12. Mass Update API

    An additional HTTP status code with status 207 will be available from V2.1 for requests that are partially successful.

    

13. Custom View Metadata API

    

    12a. Keys introduced in V2.1

    • modified_timestring

      Represents the time and date at which the custom view was last modified

    • modified_byJSON object

      Represents the name and unique ID of the user who last modified the custom view

    • last_accessed_timestring

      Represents the date and time at which the custom view was last accessed

    • created_byJSON object

      Represents the name and unique ID of the user who created the custom view

    12b. Updates in existing keys and their data types

    

    The following are the updates in get specific custom view metadata API.

    • access_typestring

      The shared_type key is renamed as access_type.

    • fieldJSON object

      From V2.1, the data type of the field key is a JSON object instead of a string. The key represents the API name and unique ID of the field in the criteria.

    • valuestring

      From V2.1, the data type of the value key is a string instead of a JSON array.

    • shared_toJSON array

      The shared_details key is renamed as shared_to. Also, from V2.1, the data type of the key subordinates is JSON object instead of boolean.

    • fieldsJSON array of objects

      From V2.1, the data type of the fields key is JSON array of objects instead of JSON array. Each object in the array represents the API name and the unique ID of the field.

14. Territories API

    

    13a. Updates in the existing key values and their data types

    • reporting_toJSON object

      From V2.1, the "parent_id" key of string type will be replaced by "reporting_to" key. This key represents the name and unique ID of the parent territory.

    • account_rule_criteriaJSON object

      From V2.1, the "criteria" key of JSON object type will be replaced by "account_rule_criteria" key. This key represents territory criteria details.

    • deal_rule_criteriaJSON object

      From V2.1, a new key "deal_rule_criteria" key is introduced. This key represents the details of deal territory rules.

    • fieldJSON object

      From V2.1, the data type of the key "field" will be JSON object. This key represents the API name and the unique ID of the field involved in the territory criteria.

    • permission_typestring

      From V2.1, a new key representing the access permission of the current user for the territory is added.

15. Changes in the Error Response

    All APIs introduced in V2.1 and the ones that have updates will have one of the following keys(in the details object) in their error responses to determine the point of error :

    • JSON Path Index
    • Resource Path Index

    1. JSON Path Index for POST/PUT

       This key is to identify an error in the input body. The json_path key will give the index at which an error has occurred.

       

    2. Resource Path Index for POST/PUT/DELETE

       This is to identify the error in the request URL. The index starts at the resource after the version number.