Multi-user Lookup in API V4
Hello everyone!
Welcome to another week of Kaizen! In this post, we will discuss multi-user lookup fields and how to handle them in API.
What is multi-user lookup?
Multi-user look up is a lookup field that lets you add multiple users to a module record. It allows you to establish many-to-many relationships between modules and users in CRM.
For instance, consider the example of a real estate firm - Zylker Real Estates. Zylker Real Estates uses Zoho CRM for managing properties, buyers, sellers, etc. The real estate agents in Zylker Real Estates are added as users . We might have one or more agents managing a single property. A multi-user lookup field in the property module allows multiple agents to have read/write access to one property record.
You can add a multi-user lookup field to a module through the module builder. Go to Setup > Customization > Modules and Fields > {Module}. This field can be added in all modules except the Calls, Tasks,Meetings and Linking Modules. You can add only 1 multi-user lookup field in a module that can include up to 10 users. In the screen-shot below, multi-user lookup field "Associated Agents" is added with full record accessibility.
When you enable 'Allow Record Accesibility', users selected in the multi-user lookup field will be able to 'Edit', 'Delete', 'Change the owner' of that respective record. You can also grant different levels of permission to the users. You can choose from Read only, Read/Write, Full access.
Handling multi-user lookups through API
Let us see how to handle multi-user lookup fields through API. Note that, we have used the V4 API in examples, here.
Inserting value to multi-user field
You can use Insert Records API to add a record with multi-user lookup. This support is available only from CRM API version 2.1 and up.
For example, for Zylker Real Estates a new property "Villa" can be added with the below API request. Two associated agents are also added.
Details Required :
- ID of the users that you want to add to the multi-user field. You can get this from Get Users API In this example 431581000000278001 is the ID of the user J Smith and 431581000000258001 is the ID of the user Patricia Boyle.
- The connectedlookup_apiname and api_name for the multi-user field that you want to add. You can obtain these details from the multi-user field's json object in the response of Field Meta Data API of the Properties module.
Sample Response to field meta data API
Request URL : {api-domain}/crm/{version}/settings/fields?module={module_api_name}
Request Method: GET
{ "fields": [ { . . "display_label": "Associated Agents", . . "api_name": "AssociatedAgents", . . "multiuserlookup": { "display_label": "Users", "linking_module": { "api_name": "Properties_X_Users", "id": "431581000000701218" }, "lookup_apiname": "userlookup221_7", "connected_module": null, "api_name": "Users7", "connectedlookup_apiname": "Agents", "id": "431581000000701345", "record_access": true }, . . } ] } |
Sample Input to add a record with multi-user lookup
Request URL : {api-domain}/crm/{version}/{module_api_name}
Request Method: POST
{ "data": [ { "Property_Name": "Villa", "AssociatedAgents": [//api_name { "Agents": {//connectedlookup_apiname "id": "431581000000278001" }, }, { "Agents": {//connectedlookup_apiname "id": "431581000000258001" }, } ], } ] } |
This is what the record looks like in UI.
Sample Response
{ "data": [ { "code": "SUCCESS", "details": { "Modified_Time": "2023-05-25T12:52:03+05:30", "Modified_By": { "name": "Patricia Boyle", "id": "431581000000258001" }, "Created_Time": "2023-05-25T12:52:03+05:30", "id": "431581000000697288", "Created_By": { "name": "Patricia Boyle", "id": "431581000000258001" }, "$approval_state": "approved" }, "message": "record added", "status": "success" } ] } |
Fetching the value of multi-user field
You can use Get Records API to fetch details of your multi-user lookup field. Note that it is returned in the response only when you fetch a specific record. Let us see how to fetch details of a record.
Details Required : ID of the record for which we need to fetch the multi-user field's value
Request URL : {api-domain}/crm/{version}/{module_api_name}/{record_id}
Request Method: GET
Sample Response
{ "data": [ { "AssociatedAgents": [ { "Agents": { "name": "Patricia Boyle", "id": "431581000000258001" }, "id": "431581000000697290" }, { "Agents": { "name": "J Smith", "id": "431581000000278001" }, "id": "431581000000697289" } ], "id": "431581000000697288", "$canvas_id": null, "$has_more": { "AssociatedAgents": false } } ] } |
Here the highlighted IDs are the IDs of the linking modules created for the multi-user fields. Unlike linking modules for multi-select lookups, these are not exposed in the UI.
Disassociating users from the multi-user lookup field
You can use Update Records API with the key _delete to disassociate users from a multi-user lookup. You can refer to the sample input below for the same.
Details Required : ID of the module records and ID of the linking module of multi-user lookup. These can be obtained from the GET Record Response.
Sample Input
Request URL : {api-domain}/crm/{version}/{module_api_name}/{record_id}
Request Method: PUT
{ "data": [ { "AssociatedAgents": [ { "id" : "431581000000697061" , "_delete" : null } ] } ] } |
Here the highlighted ID inside the AssociatedAgents array is the ID of the linking module record. You can obtain the ID from the Get Records API response
Sample Response
{ "data": [ { "code": "SUCCESS", "details": { "Modified_Time": "2023-05-24T15:15:28+05:30", "Modified_By": { "name": "Patricia Boyle", "id": "431581000000258001" }, "Created_Time": "2023-05-24T14:30:23+05:30", "id": "431581000000697060", "Created_By": { "name": "Patricia Boyle", "id": "431581000000258001" } }, "message": "record updated", "status": "success" } ] } |
We hope you found this post useful and it has given you a better understanding of multi-user lookups. We will meet you next week with another interesting post.
If you have any questions, let us know in the comment section or write to us at support@zohocrm.com
Access your files securely from anywhere
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Mable Mary M P
Sticky Posts
Kaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provideClient Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! CommandsExtension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use APIKaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achievedExtension pointers for integrating Zoho CRM with Zoho products #8: Upload and manage Zoho Workdrive folders and files from within Zoho CRM
Keeping records on your customers and business prospects is essential for tracking data, conducting follow-ups, and running a business smoothly. When you use two separate applications, and store relevant data in each, checking and tracking data becomes
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho DataPrep Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho Campaigns Resources
Zoho CRM Resources
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー