Functions - Integration Tasks

Functions - Integration Tasks

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 Space > APIs > 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 Space > APIs > CRM API > API Names.
  • Click on a module name. For example: Leads



  • The API Name 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 is 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
  1. resp = zoho.crm.getRecords("Leads",1,20,{"converted":"true"});

Note

In the above sample, "converted" is an optionalDataMap.

Syntax: (using Version 1.0 APIs)

<response>=zoho.crm._getRecords(<module_name>, [<from_index>],[<to_index>]);

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

  1. resp = zoho.crm.getRecordById("Leads", 2938383000000392001);

Syntax: (using Version 1.0 APIs)

<response>=zoho.crm._getRecordById(<module_name>, <record_ID>);

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

  1. data = Map();
  2. data.putAll({"Last_Name":"Bruce Wills", "Company":"Zillum"});
  3. optionalMap = Map();
  4. optionalMap.put("trigger", ["workflow","approval", "blueprint"]); // pass "trigger" as empty [] to not execute workflow
  5. resp = zoho.crm.create("Leads", data, optionalMap);

Sample Response

  1. {"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"}}

Syntax: (using Version 1.0 APIs)

<variable>=zoho.crm._create(<module_name>,{<field_values>});

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 record, 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

  1. resp = zoho.crm.bulkCreate("Leads", [{"Last_Name":"Deborah"},{"Last_Name":"James"}], {"trigger":["workflow","blueprint","approval"]});

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

  1. resp = zoho.crm.update("Leads", 2938383000000392001, {"Company":"Zillum Corp"});

Sample Response

  1. {"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"}}

Syntax: (using Version 1.0 APIs)

<response>=zoho.crm._updateRecord(<module_name>, <record_ID>, <New values as map object>);

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: (<field>:<condition>:<value>). The <field> stands for the CRM field label name and <value> 
stands for it's respective value. The <condition> may be
  • equals
  • starts_with (STRING)
<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

  1. resp = zoho.crm.searchRecords("Leads", "(Company:equals:Zillum)");

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.

Syntax: (using Version 1.0 APIs)

<response>=zoho.crm._searchRecords(<module_name>, <criteria>, [<from_index>],[<to_index>]);

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

  1. resp = zoho.crm.getRelatedRecords("Campaigns", "Leads", 2938383000000392001);

To fetch Tasks related to a Lead

  1. resp = zoho.crm.getRelatedRecords("Task", "Leads", 2938383000000392001);

Syntax: (using Version 1.0 APIs)

<response>=zoho.crm._getRelatedRecords(<module_name>, <parent_module_name>, <record_ID>, [<from_index>],[<to_index>]);

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"}

Sample Input

To update product quantity

  1. resp = zoho.crm._updateRelatedRecords("Products",2938383000000392001, "Leads", 2938383000000392001, {"Product_Quantity":"50"});

Syntax: (using Version 1.0 APIs)

<response>=zoho.crm._updateRelatedRecords(<module_name>, <parent_module_name>, <record_ID>, [<from_index>],[<to_index>]);

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

  1. 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 } });

    • Related Articles

    • Setting up Functions

      All custom functions programmed by your Developers are listed in the Functions page. By this way, programmers can focus on the developing Deluge Scripts where as CRM Administrators can deploy the thoroughly tested custom functions as per requirement. ...

    • Using API Key - Serverless Functions

      Introduction A severless function within your CRM can be invoked from any third-party application or within the CRM using a webhook. However, generally most of the webhooks do not support OAuth2, save for a few of them. In that case, you can execute ...

    • Overview - Serverless Functions

      Serverless architecture, also known as “Function-as-a-service”(Faas), provides a platform for developers to execute their own codes in response of various business events. In Zoho CRM, all these codes can be written through deluge scripts and can be ...

    • Authentication - Serverless Functions

      Authentication Method A serverless function within your CRM can be invoked from any third-party application or within the CRM. However, commonly not all of the applications support a single authentication method. Keeping that in mind, we have two ...

    • Types of Inputs - Serverless Functions

      The input for the function can be acquired in the following types Parameters Parameters are passed in URL of query string and the data passed in the post "form-data" section in an input. The "params" in the crmAPIRequest map contains these parameters ...