Changelogs
We update Zoho Vertical Solutions APIs frequently with new features to suit your evolving business needs. These changelogs document all the notable changes made to Vertical Solutions APIs in version 3.
API Domain
For V2.1 and above versions, you must use the dedicated domain name to make API calls. This is helpful in serving CORS requests.
https://{your-solution-name}.zohoplatform.com/(US) (Default domain)
Europe - https://{your-solution-name}.zohoplatform.eu/(Europe)
For more information, refer to Multi DC Support. If you fire API calls with a domain other than https://www.www.zylkercorp.zohoplatform.{dc}, the system will throw INVALID_HOST error with HTTP status 400.
Version V3
The Vertical Solutions APIs with updates that apply to the V3 version are listed below.
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.
Activities From this version you cannot make API calls to the Activities module. You must make module-specific calls such as Meetings, Calls, and Tasks.
Modules API
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.
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.
The modules Email_Analytics, Services__s, Appointments__s, and Appointments_Rescheduled_History__s are introduced.
The property $client_portal_permission is introduced that indicates whether the records and the notes in that module can be shared with other users of the portal.
Get Profiles API
The following keys are introduced:
type:
Represents if the profile is a normal_profile, lite_profile or portal_profile.
profile_permissions: This key gives the details of the view, create, edit, and delete permissions given to the profile for different modules. Note that this array is rendered in the response only when you fetch a specific profile.
The modules Email_Analytics, Services__s, Appointments__s, and Appointments_Rescheduled_History__s are introduced.
The property $client_portal_permission is introduced that indicates whether the records and the notes in that module can be shared with other users of the portal.
Users API
The territories key is removed from the Get Users response.
New error case is added when a user rejects the invitation sent to be added to the org.
Four new APIs are included in this version to get, assign and update the territories of a user, validate the open records before transferring them, and to delink and transfer the open records in the territory to a new user.
Organization API
The deletable_org_account key is introduced which represents whether the account related to that org is deletable or not.
Fields and Layouts Metadata API
6a. 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.
6b. 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.
6c. 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.
6d. 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.
6e. 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.
6f. 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.
Leads: New fields Converted_Contact, Converted_Deal, and Converted_Account are introduced. Note that these keys are rendered in the response when you fetch a converted lead by its ID or using the parameter "converted=true" for the Leads module in the Get Records API. For the non-converted leads, the value for the above keys will be "null".
The boolean property searchable is introduced, which represents whether the field in that module is searchable.
The boolean property virtual_field is introduced which represents if the field is virtual. Virtual fields are those that are used for reference purposes in subforms, multi-select lookups, multi-select user lookups, ISONLINE, FULL_NAME etc. These fields contain meta properties but do not have actual values.
The property sharing_properties is introduced, which represents if the user has access to the records that the field looks up to.
The boolean property enable_colour_code is introduced that represents whether color-coding is enabled for a field.
The property colour_code is introduced in pick_list_values array. This represents the color code used for that picklist's value.
The values of the status key are changed. It represents the status of the layout to the user. The values are "active", "inactive", "downgrade", and "hidden".
The parameter include=allowed_permissions_to_update is introduced to get the read/write customization permission for a field. For example: "read_only":true denotes that the field can be used as a read-only field.
Deals: The data type of the key forecast_category in Stage Probability Mapping of the Deals module is changed from string to JSON object.
Users: New fields Number_Separator and Decimal_Separator are introduced.
Meetings: The data type of the key Remind_At is changed to multireminder.
Layouts Metadata: Besides the above changes, the following are the additional changes in this API.
The "sections" array has a new key "id" that represents the unique ID of that section.
New keys source and generated_type are added. "source" represents whether the layout was created from a campaign integration, platform or marketplace plugin, or Vertical Solutions.
"generated_type" represents whether the layout is custom or system-generated.
Custom View Metadata API
7a. 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
7b. 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.
A new key locked is included in the response. This represents if the current custom view is locked for editing. When a custom view is locked, only Admins and creators can modify it. We have also added the related error cases.
Related Lists Metadata API
The parameter layout_id is supported from this version. When you specify a layout's ID, the metadata of the related lists in that layout will be fetched.
The keys customize_sort, customize_fields, customize_display_label are introduced in the response.
The related list Appointments_Rescheduled_History__s is introduced.
Insert and Update Records APIs
9a. 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.
9b. 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 arrayQuoted_Items
JSON arrayproduct
JSON objectProduct_Name
JSON objectquantity
IntegerQuantity
Integertotal_after_discount
IntegerTotal_After_Discount
Integernet_total
IntegerNet_Total
Integerbook
JSON objectPrice_Book_Name
JSON objectlist_price
IntegerList_Price
Integertotal
IntegerTotal
Integerproduct_description
StringDescription
Stringline_tax
JSON arrayLine_Tax
JSON array9c. 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.
Meetings module: The format of Remind_At for recurring meetings is changed. This array contains the "unit" and "period" keys in each JSON object.
Tasks module: The "FREQ" key under "Remind_At" JSON object is not supported. From this version, you cannot set up multiple reminders for a task. This "Remind_At" JSON object will be in the format "ALARM":"ACTION=EMAIL_or_POPUP;TRIGGER=DATE-TIME:<DateTime_in_ISO8601>".
wizard_connection_path: This JSON array accepts the IDs of the wizard connection paths when you create a record in a wizard.
In the response, the key approval_state is added that represents the approval state of the record if it enters the approval process.
Relevant error codes for the Appointments module are added.
Get Records API
10a. 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
10b. 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.
10c. 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 Vertical Solutions
Events API
- $event_cancelledboolean
Represents if the event is canceled or not
fields is a mandatory parameter when you want to fetch all records from a module. This parameter takes up to 50 field API names you want in the response.
If your requirement is to fetch under 2000 records, use the "page" and "per_page" parameters (page=1 to 10, per_page=200).
If you want to paginate for more than 2000 records, use the "page_token" parameter you receive in the first response. Using this next page token in the consecutive requests, you can navigate and fetch up to 100,000 records.
Note that for this case, you can use page_token from page=2 itself, instead of page and per_page parameters. If there are more records, the API responses, will have "next_page_token" and "previous_page_token" for easy pagination.Note that in both the above scenarios, the maximum records per request will be only 200.
You cannot use the cvid and sort_by parameters together. When you use sort_by, you can only sort the records based on the Modified_Time, Created_Time, and id fields.
wizard_connection_path: This JSON array gives the IDs of the connections that represent the sequence in which the user filled up valid information on a screen. This key is available in the response only when you fetch a specific record.
A new parameter on_demand_properties = "$client_portal_permission" returns the "$client_portal_permission" JSON object in the response. The boolean values to the keys "record" and "notes" represent whether the record is visible to users of the portal and if notes can be shared to others, respectively. You can use this parameter only while fetching a specific record.
In the Tasks module, the parameter uid is introduced to fetch the recurring tasks by their recurring IDs($u_id).
Convert Lead API
A new API Get Lead Conversion Options is introduced. This API fetches the records in Deals, Contacts, and Accounts modules that match the data in the lead record. You can then convert the lead and associate it to the relevant records in these modules to avoid duplicate data errors.
When you convert a lead, even the multi-select lookup and multi-select user lookup fields are converted.
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.
Search Records API
You can search for and fetch a maximum of 2000 records using this API. Exceeding this limit will result in the "LIMIT_REACHED" error.
New error cases are added.
Update Subform API
The update functioning has been modified. Henceforth, the update operation on a subform record will append the provided data with the existing data. For instance, consider a subform "Proficiency", which has a record with ID "50402XXXX123". When you update the parent record with the subform data but without sending the record ID of the existing subform record, the subform will now have two rows with IDs "50402XXXX123" and "50402XXXX456"(newly appended record ID).
Also, providing the key "_delete" as "null" will delete the subform record.
New sample input cases are added
Tags 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.
In Get tags API, a new key colour_code is introduced. This key represents the hex value of the color you have chosen for that tag.
You can also color-code your tags while creating or updating them. Specify one from the list of supported colors for tags in the request body.
Records Share 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.
A new key type is included in Get Shared Records Details, Update Share Permissions, and Revoke Permissions APIs. This key represents whether the record is shared publicly to all users in the org or privately to a specific user.
The user object in the response of Get Shared Records API is now changed to shared_with. This key contains the details of the user that the record is shared with.
Delete Variables API
You cannot delete a variable if it is in use in other places like webhooks, custom links, templates, etc. The relevant error cases are added.
Get Wizards API
The response contains the following new keys:
conditional_rules: For each screen, there will be an array of conditional rules. Each rule will have criteria and set of actions.
message: You can now display acknowledgment messages in wizards. The response contains the title and content of the acknowledgment.
buttons: This key contains the details of the buttons used in various segments of a screen.
Query API
You can use pagination (through OFFSET and LIMIT) and fetch up to 10,000 records using this API.
The select query now supports "alias". You can fetch the record's details and receive the relevant data in the field specified in the alias.
You can now fetch the owner's profile details such as ID, name, created_by, modified_by, description, created_time, modified_time, and the details of the role such as ID, name, reporting_to, share_data_with_peers, description from a module.
New format introduced for module API name in the select query. All module names must have the prefix ! to differentiate between a module's and a field's API names.
Bulk Read API
19a. 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.
19b. 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.
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.
Mass Update API
An additional HTTP status code with status 207 will be available from V2.1 for requests that are partially successful.
Custom View Metadata API
22a. 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
22b. 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.
Territories API
23a. 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.
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
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.
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.
Get and Update Blueprints API
25a. 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.
25b. 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.
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.