Kaizen #77 - Multi-select Lookup Fields in API V4

Kaizen #77 - Multi-select Lookup Fields in API V4

Hello everyone!
Welcome back to another post in the Kaizen series!
This week, we will discuss how to add data to multi-select lookup fields using the insert records API.
Note that this support is available only from CRM API version 2.1 and up. We have used the V4 API in examples, here.

What is a multi-select lookup field?

Consider an insurance company using CRM to track its policies, customers and their purchased policies. In CRM, we will use the custom modules Policies and Holders to store policy details and customers' personal details, respectively.

Here, each holder can have multiple policies and the same type of policy can be held by multiple holders.
So, there is a need to establish many-to-many relationships which you cannot achieve through a lookup field.

Multi-select lookup fields solve exactly this!
They allow you to associate multiple records with each other from two modules. The related modules' records are also available as related lists.

Linking Module 

When you have a multi-select lookup that connects two modules, a linking module is created that contains data of the two connected modules.
Here, there will be two lookup fields—one pointing to Policies and the other pointing to Holders.



This is how the linking module looks in the UI:




Earlier, using V2 APIs, you had to make a POST call to this linking module and add data related to the two modules. Refer to this post for details.

From V2.1, you can directly add data to a multi-select lookup field while inserting a record itself.

Example Scenario

Let us consider the same example of Policies and Holders.
Policies and Holders contain Holders and Policies_Held multi-select lookup fields, respectively.
There are four policies viz., Life, Health, Auto, and Home.
Similarly, Allison, Smith, Jack, and Derek are policy holders and hold single or multiple policies.

Here is how a policy record looks like in the UI.
Holders is the multi-select lookup field and contains the details of the holders of this policy. You can also see Holders as a related list.



Here is how a record from the Holders module looks like in the UI with the Policies_Held related list.



Let us discuss how to associate a policy holder directly while creating a policy through the Insert Records API.
API names you need before using the API:
  • API names of the multi-select lookup fields in the modules they appear.
  • API names of the lookup fields in the connected module. Example, the API name of the multi-select lookup field in Holders is Policies_Held, while that of the lookup in the connected module is Policies.
    You can use the Fields Metadata API for Policies and Holders to get these details.

Request URL: {{api-domain}}/crm/v4/Policies
Request Method: POST
Scope: ZohoCRM.modules.ALL or ZohoCRM.Policies.ALL/CREATE

Input Body:

{
    "data": [
        {
            "Name": "105_Travel",
            "Policy_Type": "Travel",
            "Policy_Period": "5 years",
            "Premium_Amount": 5000.00,
            "Payment_Model": "Annual",
            "Holders": [ //API name of the multi-select lookup field in Policies module
                {
                    "Holders": { //API name in Policies
                        "name": "Allison",
                        "id": "3652397000011357033" //Record ID in the Holders module
                    }
                },
                {
                    "Holders": {
                        "name": "Jack",
                        "id": "3652397000011357001" //Record ID in the Holders module
                    }
                }
            ]
        }
    ]
}

UI after successful insertion:


Deluge Code:
Policyinfo =  {
 "data":[{
  "Name": "105_Travel",
            "Policy_Type": "Travel",
            "Policy_Period": "5 years",
            "Premium_Amount": 5000.00,
            "Payment_Model": "Annual",
            "Holders": [
                {
                    "Holders": {
                        "name": "Allison",
                        "id": "3652397000011357033"
                    }
                }
            ]
   }]};
response = invokeurl
[
 type: POST
 content-type: "application/json"
 parameters: Policyinfo.toString()
 connection: "ZohoCRM"
];

info response;
return "";

Here is the input body to insert a holder in the Holders module with the multi-select lookup field Policies_Held.

{
    "data": [
        {
            "Name": "Sandra",
            "Policies_Held": [ //API name of the multi-select lookup field in Holders
                {
                    "Policies": { //API name in the connected module  
                        "name": "105_Travel",
                        "id": "3652397000011358003" //Record ID in Policies
                    }
                },
                {
                    "Policies": {
                        "name": "101_Home",
                        "id": "3652397000011353001"
                    }
                }
            ]
        }
    ]
}

Deluge Code:
Holderinfo =  {
    "data": [
        {
            "Name": "Sinatra",
            "Policies_Held": [
                {
                    "Policies": {
                        "name": "105_Travel",
                        "id": "3652397000011358003"
                    }
                },
                {
                    "Policies": {
                        "name": "101_Home",
                        "id": "3652397000011353001"
                    }
                }
            ]
        }
    ]
};
response = invokeurl
[
 type: POST
 content-type: "application/json"
 parameters: Holderinfo.toString()
 connection: "ZohoCRM"
];

info response;
return "";

We hope you found this post useful. We will meet you next week with another interesting post.
Write to us at support@zohocrm.com if you have any questions, or let us know in the comment section.


Cheers!