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.0 | Equivalent in API Version 2.0 |
|---|---|
| {MODULE}ID (Ex. LEADID,CONTACTID,etc) | id |
| SMOWNERID | id given within the Owner JSONObject. |
| {MODULE} OWNER (Ex. Lead Owner, Case Owner) | name given within Owner JSONObject. |
| SMCREATORID | id given within Created_By JSONObject |
| Created By | name given within Created_By JSONObject. |
| MODIFIEDBY | id given within Modified_By JSONObject |
| Modified By | name given within Modified_By JSONObject. |
Field Format types:
| Field Type | V1.0 Format | V2.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", |
| <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" }, |
| Layout | N/A | "Lookup_1": { "name": "9500495sam", "id": "1386586000001815005" } |
API Methods
| Method Name | Purpose |
|---|---|
| getRecords | To retrieve all users data specified in the API request |
| getRecordById | To 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 |
| deleteRecords | To delete the selected records |
| convertLead | To convert lead to potential, account and contact |
| getRelatedRecords | To 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 |