V2 Vs V1

The Version 2.0 update of Zoho APIs had a great impact on the usage of APIs and Functions (previously custom functions). The working of the APIs are mostly the same, but the syntax, output and methods are different.

The purpose of this document is to provide the clear difference between the two APIs and also to make users understand the version 2.0 better.

What's different in V2:

  • API response and input formats supports only JSON.
  • APIs will be authenticated by OAuth 2.0 protocol.
  • There are Api Names for modules, fields and related_lists, in version 2.0, instead of display label as in Version 1.0 APIs.
  • API call limits are based on 24 hour rolling window, whereas in V 1.0, API call limit is based on PST timezone.
  • Date time values given in ISO 8601 date time format (2018-03-28T10:32:45+05:30).
  • All API names starting with $ are read-only attributes.
  • When you GET a record, the response for empty fields are JSON Null.
  • Module API names can be fetched using "https://www.zohoapis.com/crm/v2/settings/modules" - Request URL
  • In insert, update and upsert APIs, automated actions like workflow, approval and blueprint can be triggered for all the records using the key “trigger”:[“approval”,”workflow”,”blueprint”]
  • In GET APIs, responses will have an info JSONObject. Ex:

    "info": {
        "per_page": 200,
        "count": 1,
        "page": 1,
        "more_records": false

    • page: To get the list of records from the respective pages. Default value is 1.
    • per_page: To get the list of records available per page. Default value is 200.
    • more_records is to know whether to make extra API call to fetch next set of records
  • getMyRecords(v1.0 API) can be fetched using searchRecords API in v2.0

Field Attribute changes:

In API Version 1.0Equivalent in API Version 2.0
SMOWNERIDid given within the Owner JSONObject.
{MODULE} OWNER (Ex. Lead Owner, Case Owner)name given within Owner JSONObject.
SMCREATORIDid given within Created_By JSONObject
Created Byname given within Created_By JSONObject.
MODIFIEDBYid given within Modified_By JSONObject
Modified Byname given within Modified_By JSONObject.

Field Format types:

Field TypeV1.0 FormatV2.0 Format
Single Line<FL val="Single_Line 1"> <![CDATA[this is single line]]> </FL>"Single_Line_1": “This is single line”,
Multi Line<FL val="Multi-Line 1"><![CDATA[this is multi line second line]]></FL>"Multi_Line_1": "This is \multi line\second line",
Email<FL val="Email"><![CDATA[email@zoho.com]]><FL>"Email_1": "email1@email.com",
Phone<FL val="Phone 1"><![CDATA[9900000000]]></FL>"Phone_1": "9900000000",
Picklist<FL val="picklist1"><![CDATA[one]]></FL>"picklist1": "one",
Multi-select Picklist<FL val="Multi-Select 1"><![CDATA[Option1;Option 2]]></FL>"Multi_Select_1": [
    "Option 1",
    "Option 2"
Date<FL val="Date 1"><![CDATA[2018-03-29]]></FL>"Date_1": "2018-03-29",
Date/Time<FL val="Date/Time 1"><![CDATA[2018-04-07 10:00:00]]></FL>"Date_Time_1": "2018-04-07T10:00:00+05:30",
Number<FL val="Number 1"><![CDATA[50000]]></FL>"Number_1": 50000,
Currency<FL val="Currency 1"><![CDATA[230000500]]></FL>"Currency_1": 230000500,
Decimal<FL val="Decimal 1"><![CDATA[1234.9]]></FL>"Decimal_1": 1234.9,
Percent<FL val="Percent 1"><![CDATA[12.3]]></FL>"Percent_1": 12.3,
Long Integer<FL val="Long Integer 1"><![CDATA[6780000000780000]]></FL>"Long_Integer_1": "6780000000780000",
Checkbox<FL val="Checkbox 1"><![CDATA[true]]></FL>"Checkbox_1": true,
URL<FL val="URL 1"><![CDATA[https://www.zoho.com]]></FL>"URL_1": "https://www.zoho.com",
Lookup<FL val="Lookup 1"><![CDATA[9500495sam]]></FL>"Lookup_1": {
    "name": "9500495sam",
    "id": "1386586000001815005"
Record Owner<FL val="SMOWNERID">1386586000000078001</FL>
<FL val="Lead Owner"<>![CDATA[BruceWills]]></FL>
"Owner": {     "name": "Bruce Wills",     "id": "1386586000000078001"   },
LayoutN/A"Lookup_1": {
    "name": "9500495sam",
    "id": "1386586000001815005"

API Methods

Method NamePurpose
getRecords To retrieve all users data specified in the API request
getRecordByIdTo retrieve individual records by record ID
getDeletedRecordIds To retrieve the list of IDs of deleted records from recycle bin
insertRecords  To insert records into the required Zoho CRM module
updateRecords To update or modify the records in Zoho CRM
getSearchRecordsByPDC To search the values based on pre-defined columns
deleteRecordsTo delete the selected records
convertLeadTo convert lead to potential, account and contact
getRelatedRecordsTo retrieve records related to a primary module
getFields To retrieve details of fields available in a module
updateRelatedRecords To update records related to another record
getUsers To retrieve the list of users in your organization
uploadFile To attach a file to a record
delink To disassociate the relationship between parent and child records
downloadFile To download a file attached to a record
deleteFile To delete a file attached to a record
uploadPhoto To add a photo to a contact or lead
downloadPhoto To download the photo of a contact or lead
deletePhoto To delete a photo of a contact or lead
getModules To retrieve all modules from Zoho CRM account
searchRecords To retrieve the records that match your search criteria