Functions - Integration Tasks
As you might already know, the update to Version 2.0 APIs played a major part in using custom functions, now named "Functions". This guide will help you use functions integration tasks that are based on the new APIs.
Getting Started
For starters, the basic difference between Version 1.0 and 2.0 of Zoho APIs is that Field Names are used in the former and API Names are used in the latter.
To get the API Names of modules,
- Go to Setup > Developer Hub > APIs and SDKs > CRM API > API Names.
- The API Names of the modules are listed in the API Names tab.
To get the API Names of fields in modules,
- Go to Setup > Developer Hub > APIs and SDKs > CRM API > API Names.
- Click on a module name. For example: Leads
- The API Names tab contains the API Names of fields. These fields are to be used in the code and NOT the names in the Field Label tab.
Get Records
Records, containing information, can be fetched from multiple supported modules of CRM. You can get the records using the zoho.crm.getRecords() task.
Syntax: (using Version 2.0 APIs)
<response>=zoho.crm.getRecords(<module_name>, [<page>],[<perPage>], {<optionalDataMap>}, <connections>);
| Params | Description |
|---|---|
| <response> | The response with the LIST of records matching the fetch criteria. |
| <module_name> | The name of the module from which the record has to be fetched. Supported modules are Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom. |
| <page> (optional) | To get the list of records based on pages. It is of the NUMBER datatype. Default - 1. |
| <perPage> (optional) | Used to get the list of records available per page. It is of the NUMBER datatype. Default - 200. |
| <optionalDataMap> | Used to get the list of records using params other than page and per_page. |
| <connections> | Displays the connectors associated with the function. Datatype is STRING. |
Sample Input:
resp = zoho.crm.getRecords("Leads",1,20,{"converted":"true"});
Note:
- In the above sample, "converted" is an optionalDataMap.
Get Record by ID
Getting a list of records is quite good, but what if you want to fetch details about a specific record. You can use the zoho.crm.getRecordById() task, to get the information about a particular record.
Syntax: (Using Version 2.0 APIs)
<response>=zoho.crm.getRecordById(<module_name>, <record_ID>, <connections>);
| Params | Description |
|---|---|
| <response> | The response which is returned as a MAP. |
| <module_name> | The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom. |
| <record_ID> | The ID of the record to be fetched. It is of NUMBER datatype. |
| <connections> | Displays the connectors associated with the function. Datatype is STRING. |
Sample Input:
resp = zoho.crm.getRecordById("Leads", 2938383000000392001);
Create a record
Set up the functions in a way that records are automatically created based on certain actions. For ex: you can trigger the function to create a record in tasks upon changing the status of a lead. The zoho.crm.create() task is used to create records.
Syntax: (Using Version 2.0 APIs)
<variable>=zoho.crm.create(<module_name>,{<dataMap>}, {<optionalDataMap>}, <connections>);
| Params | Description |
|---|---|
| <response> | The response which is returned as a MAP. |
| <module_name> | The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom. |
| <dataMap> | The name of the fields in the module which are to be specified during creation of the record. For ex: {"Last_name":"Zoho CRM"} |
| <optionalDataMap> | Represents all the data maps other than input JSON. |
| <connections> | Displays the connectors associated with the function. Datatype is STRING. |
Sample Input:
data = Map();
data.putAll({"Last_Name":"Bruce Wills", "Company":"Zylker"});
optionalMap = Map();
optionalMap.put("trigger", ["workflow","approval", "blueprint", "pathfinder", "orchestration"]); // pass "trigger" as empty [] to not execute workflow
resp = zoho.crm.create("Leads", data, optionalMap);
Sample Response:
{"Modified_Time":"2018-03-26T14:33:01+05:30","Modified_By":{"name":"Ben","id":"2938383000000132011"},"Created_Time":"2018-03-26T14:33:01+05:30","id":"2938383000000389001","Created_By":{"name":"Ben","id":"2938383000000132011"}}
Create bulk records
Set up the functions in a way that records are automatically created based on certain actions. For ex: you can trigger the function to create multiple records, in contacts, accounts, tasks, deals, etc, upon changing the converting a lead to a contact. The zoho.crm.bulkCreate() task is used to create records.
Syntax: (Using Version 2.0 APIs)
<variable>=zoho.crm.bulkCreate(<module_name>,[record1, record2]);
| Params | Description |
|---|---|
| <response> | The response which is returned as a MAP. |
| <module_name> | The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom. |
| [record1, record2] | The LIST which contain the information about the records to be created. |
Sample Input:
resp = zoho.crm.bulkCreate("Leads", [{"Last_Name":"Deborah"},{"Last_Name":"James"}], {"trigger":["workflow","blueprint","approval", "pathfinder", "orchestration"]});
Update a record
Often, there are times when you would have to update records. Editing the existing information, adding additional information, etc can be done automatically by setting the zoho.crm.update() task, which automatically updates a record based on the programmed scenario.
Syntax: (Using Version 2.0 APIs)
<response>=zoho.crm.update(<module_name>, <record_ID>, <dataMap>, {<optionalDataMap>}, <connections>);
| Params | Description |
|---|---|
| <response> | The response which is returned as a MAP. |
| <module_name> | The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom. |
| <record_ID> | The ID of the record to be updated. It is of NUMBER datatype. |
| <dataMap> | Key-value pairs with updated record information. |
| <optionalDataMap> | Represents all the data maps other than input JSON. |
| <connections> | Displays the connectors associated with the function. Datatype is STRING. |
Sample Input:
resp = zoho.crm.update("Leads", 2938383000000392001, {"Company":"Zylker Corp"});
Sample Response:
{"Modified_Time":"2018-03-26T15:17:39+05:30","Modified_By":{"name":"Ben","id":"2938383000000132011"},"Created_Time":"2018-03-26T14:39:28+05:30","id":"2938383000000392001","Created_By":{"name":"Ben","id":"2938383000000132011"}}
Search a record
Search for specific records by specifying the criteria for the search. The searched records can be used to perform actions anywhere. Searching for a record requires the module name and the search criteria to be specified.
Syntax: (Using Version 2.0 APIs)
<response>=zoho.crm.searchRecords(<module_name>, <criteria>, [<page>],[<perPage>], <connections>);
| Params | Description |
|---|---|
| <response> | The response with the LIST of records matching the fetch criteria. |
| <module_name> | The name of the module from which the record has to be fetched. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom. |
| <criteria> | The conditional statement for the search. It is of the following format: (<colname> : <operator> : <colvalue>). The <colname> stands for the CRM field label name and <colvalue> stands for it's respective value. The <operator> can contain the following:
|
| <page> (optional) | To get the list of records based on pages. It is of the NUMBER datatype. Default - 1. |
| <perPage> (optional) | Used to get the list of records available per page. It is of the NUMBER datatype. Default - 200. |
| <connections> (optional) | Displays the connectors associated with the function. Datatype is STRING. |
Sample Input:
resp = zoho.crm.searchRecords("Leads", "(Company:equals:Zylker)");
Note:
- Search records by PDC is not available in Version 2.0.
- If a column contains null values, zoho.crm.searchRecords DOES NOT report them in a <> statement.
- At any given time, a maximum of 200 records can be fetched.
Get Related Records
There are various components of CRM which can be used to store information about a particular lead or contact. For example, a lead may contain a list of notes, a couple of deals, calls associated, etc. Searching for a note related to a particular record in a module can be done using the zoho.crm.getRelatedRecords() task.
Syntax: (Using Version 2.0 APIs)
<response>=zoho.crm.getRelatedRecords(<relation_name>, <parent_module_name>, <record_ID>, [<page>],[<perPage>], <connections>);
| Params | Description |
|---|---|
| <response> | The response with the LIST of records matching the fetch criteria. |
| <relation_name> | The name of the module (also called sub module) from which the record has to be fetched. It is of STRING datatype. Supported modules are: Notes, Quotes, Products, Tasks, Campaigns, Events, Calls. |
| <parent_module_name> | The name of the module to which the sub module belongs to. For ex: "Notes can belong to a "Leads" parent module. It is of STRING datatype. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom. |
| <record_ID> | The ID of the parent module record that needs to be fetched. It is of NUMBER datatype. |
| <page> (optional) | To get the list of records based on pages. It is of the NUMBER datatype. Default - 1. |
| <perPage> (optional) | Used to get the list of records available per page. It is of the NUMBER datatype. Default - 200. |
| <connections> (optional) | Displays the connectors associated with the function. Datatype is STRING. |
Note:
- At any given time, a maximum of 200 records can be fetched.
Sample Input:
To fetch Campaigns related to a Lead:
resp = zoho.crm.getRelatedRecords("Campaigns", "Leads", 2938383000000392001);
To fetch Tasks related to a Lead:
resp = zoho.crm.getRelatedRecords("Task", "Leads", 2938383000000392001);
Update Related Records
There are various components of CRM which can be used to store information about a particular lead or contact. You can update the records related to a parent record using the zoho.crm.updateRelatedRecord() task.
Syntax: (Using Version 2.0 APIs)
<response>=zoho.crm.updateRelatedRecords(<relation_name>, <record_ID_1>, <parent_module_name>, <record_ID_2>, {<New values as map object>});
| Params | Description |
|---|---|
| <response> | The response with the LIST of records matching the fetch criteria. |
| <relation_name> | The name of the module (also called sub module) from which the record has to be fetched. It is of STRING datatype. Supported modules are: Notes, Quotes, Products, Tasks, Campaigns, Events, Calls, Emails. |
| <record_ID_1> | The ID of the record that needs to be updated. It is of NUMBER datatype. |
| <parent_module_name> | The name of the module to which the sub module belongs to. For ex: "Notes can belong to a "Leads" parent module. It is of STRING datatype. Supported modules are: Leads, Deals, Products, Contacts, Campaigns, Vendors, Accounts, Cases, Quotes, Sales Orders, Purchase Orders, Invoices and Custom. |
| <record_ID_2> | The ID of the parent module record that needs to be fetched. It is of NUMBER datatype. |
| <New Values as MAP object> | Key. Value pairs with updated record information. Ex: {"Last_Name": "Updated Name", "Fax": "555-858-3466"} |
Convert Lead
The next step after lead acquirement would be negotiations, where good prospects can be converted from leads to contacts. You can use the zoho.crm.convertLead() task, to get transfer the lead information as a contact record.
Syntax: (Using Version 2.0 APIs)
<response>=zoho.crm.convertLead(<record_ID>, <overwrite>, <notify_lead_owner>, <notify_new_entity_owner>, <account_ID>);
| Params | Description |
|---|---|
| <response> | The response which returned as a MAP. |
| <record_ID> | The ID of the record to be fetched. It is of NUMBER datatype. |
| <overwrite> | Used to overwrite the data if the lead was already converted. Datatype is BOOLEAN Should be either true or false. |
| <notify_lead_owner> | Used to send a notification to the owner of the lead, after conversion. Datatype is BOOLEAN Should be either true or false. |
| <notify_new_entity_owner> | Used to send a notification to the owner of the new entity(contact), after conversion. Datatype is BOOLEAN Should be either true or false. |
| <account_ID> (optional) | The ID of the record to be fetched. It is of NUMBER datatype. |
Sample Input:
resp = zoho.crm.convertLead(7000000037308, { "overwrite": true, "notify_lead_owner": false, "notify_new_entity_owner": true, "Accounts": "7000000037323", "Deals": { "Deal_Name": "Robert", "Closing_Date": "2016-03-30", "Stage": "Closed Won", "Amount": 56.6 } });
Invoke URL
Data doesn't flow within just your CRM. There are times when you require data to be pulled in from other services. You can use the Invoke URL method within the function to achieve data transfer operations.
Syntax: (Using Version 2.0 APIs)
<response>=invokeUrl
[
];
| Params | Description |
|---|---|
| <response> | The response which returned as a MAP. |
| <url> | The endpoint API url of the Zoho service or other third party service you wish to call. |
| <type> | The HTTP method of the API call. Could be: GET/POST/PUT/PATCH/DELETE. |
| <parameters> | Used to send params as "form-data". Basically it replaces the dynamic values present in the API with user-specific values. |
| <headers> | Used to specify request header params. They are mandatory in case connections are not used in invoke Url method. |
In case you're using the Sandbox of your CRM, there are some changes in the url of the method. Take a look below:
