Changelogs

We update Zoho CRM APIs frequently with new features to suit your evolving business needs. These changelogs document all the notable changes made to Zoho CRM APIs.

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.

Note

Navigating through code samples: In each of the code samples, newly introduced keys are presented in green, existing keys that are updated are presented in orange, and keys that are removed are presented in red.

  1. Modules API

    • Updates in the existing key values and their data types

    • Other changes

  2. Fields and Layouts Metadata API

    • Keys introduced in V2.1

    • Updates in the existing key values and their data types

    • Parameters introduced in V2.1

    • Module-wise changes in the fields metadata API

    • Other Changes

    • Keys introduced in V2.1 specific to Layouts Metadata API

  3. Insert and Update Records API

    • Keys introduced in V2.1

    • Module-wise changes in the Insert Records API

    • Other changes

  4. Get Records API

    • Keys introduced in V2.1

    • Updates in existing keys and their data types

    • Module specific updates

  5. Convert Lead API

  6. Get and Update Blueprints API

    • Keys introduced in V2.1

  7. Add and Remove Tags from Records API

  8. Get Shared Record Details API

  9. Bulk Read API

    • Updates in the existing keys in create bulk read job API

    • Updates in the existing keys in get bulk read job details

  10. Bulk Write API

  11. Mass Update API

  12. Custom View Metadata API

    • Keys introduced in V2.1

    • Updates in existing keys and their data types

  13. Territories API

    • Updates in the existing key values and their data types

  14. Changes in error responses

    • JSON Path Index for POST/PUT

    • Resource Path Index

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.

    update in module_name key value

    (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.

    generated_type is linking
    generated_type is subform

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

    generated_type is subform

    (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
    keys introduced in v2.1 for fields and layouts metadata api
    • 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.

      generated_type is linking
    • multiuserlookupJSON object

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

      generated_type is linking
    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.

      update in history_tracking and pick_list_values keys
    • data_type: For multi-user lookup fields, the data_type is multiuserlookup. Similarly, for image upload fields, the data_type is imageupload.

      datatypes multiuserlookup and 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.

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

      lead_conversion_time key
    • Users:

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

        reporting to key
      • The Time_Zone field will incorporate daylight savings.

        daylight savings in time zone field
      • 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.

        reporting to key
    • 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
    keys introduced in v2.1 for fields and 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.

      image upload field structure

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

      image upload field structure
    • 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.

      image upload field structure
    • 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.

      adding multiuserlookup in v2.1
    • 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.

      image upload field structure
    • 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.

      wizards
    • 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".

      wizards
    • wizardJSON object

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

      wizards

    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 moduleEquivalent of "Product_Details" key in V2.1
    QuotesQuoted_Items
    InvoicesInvoiced_Items
    Purchase OrdersPurchase_Items
    Sales OrdersOrdered_Items
    quoted items

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

    V2V2.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
    review process

    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.

      hasmore key
    • $sharing_permissionstring

      Represents the sharing permission of the current user

      hasmore key
    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.

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

      tax key
    • 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.

      territories
    4c. Module specific updates
    • Calls API

      calls api keys
      • Outgoing_Call_Statusstring

        Represents the status of the outgoing call

      • Scheduled_In_CRMBoolean

        Represents if the call was scheduled in Zoho CRM

    • Events API

      new event_cancelled key
      • $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.

    changes in blueprints api v2.1
    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.

      changes in blueprints api v2.1
    • $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.

      changes in blueprints api v2.1
    • 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.

      tag id added additionally from v2.1
  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.

      manage parameter removed from v2.1
    • 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.

      manage parameter removed from v2.1

      (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. 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.

      changes in bulk read api
    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.

    update in download url version from v2.1
  10. 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.

      datatype of module key updated as JSON object
    • 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.

      code key added additionally from v2.1
  11. Mass Update API

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

    massupdate
  12. Custom View Metadata API

    massupdate
    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
    massupdate

    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.

  13. Territories API

    territories api change
    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.

  14. 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.

      json path
    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.

      json path
Note
  • These error responses are rendered only for the new APIs and updated APIs in V2.1. APIs that do not have any change in V2.1 will continue to render the old error responses without these path indexes.

  • From V2.1, in the count API, there would be a 1-10 minute delay in refreshing the statistics.