Kaizen #189: Manipulating Multi-Module Lookup (MML) Field using Zoho CRM APIs

Hello everyone!

Welcome back to another week of Kaizen.

In this post, we explore the Multi-Module Lookup (MML) field in the Appointments module of Zoho CRM. You learn what an MML field is, how it works, and how to use it with Zoho CRM APIs.

Table of Contents:

• What is a Multi-Module Lookup (MML) Field in Zoho CRM?
• Use Cases for MML
  
• How  the "Appointment For" (MML) field in the "Appointments" module works?
• Creating a Record in the Appointments Module Using the Insert Records API
• Retrieving a Record from the Appointments Module Using the Get Records API
• Multi-module Lookup Using the COQL API
• Multi-module Lookup Using the Bulk Read API
• Frequently Asked Questions
  

What is a Multi-Module Lookup (MML) Field in Zoho CRM?

A Multi-Module Lookup (MML) field in Zoho CRM allows you to create a one-to-one relationship between a record in one module and a record from one of multiple other modules. Unlike a normal lookup field, which references a single module, an MML field can dynamically reference records from multiple modules. 

Without the MML field, users must create multiple lookup fields for each module, which complicates the CRM layout and user experience.

Note:

• The multi-module lookup (multi_module_lookup) data type was introduced in Zoho CRM API version 3.
• Currently, the MML field is available as a system-defined field named Appointment For in the Appointments module. 
• The Appointment For field supports lookups to both Contacts and custom modules.
• You cannot create a custom MML field in Zoho CRM.

Data Model Representation

MML's Data Model Representation

Use Cases for MML

Zylker Healthcare is a multi-specialty hospital that uses Zoho CRM to maintain its appointment scheduling process. 

In this setup, Zylker maintains two key modules:

• Contacts module - Stores records of physicians and surgeons, including attending physicians, specialists, and surgeons who diagnose and refer patients.
• Patients module - A custom module used to maintain records of all patients.

To improve the appointment booking process, Zylker uses the "Appointment For" Multi-Module Lookup (MML) field in the Appointments module. This field lets Zylker manage an appointment with either a Physician/Surgeon or a Patient, eliminating the need for multiple lookup fields.

How  the "Appointment For" (MML) field in the "Appointments" module works?

• When creating an appointment, the user selects the "Appointment For" field.
• The field displays records based on the selected module, either the Contacts or  Patients. 
• The user selects the appropriate record (Contact or Patients) for the appointment.
• A related list is automatically created in the selected module (Contact or Patients) as the Open Activities / Closed Activities to display all appointments associated with that record.
  

Creating a Record in the Appointments module using the Insert Records API

Before creating a record in the Appointments module via the Insert Records API, make sure you know the API names of the system-defined mandatory fields. These fields are required to create an appointment successfully.

System-defined Mandatory Fields:

• Appointment_For (MML field)
• Service_Name
• Appointment_Start_Time
• Appointment_Name
• Member
• Location

The below image shows how these system-defined mandatory fields appear in the Appointments module UI:

System-defined mandatory keys in the Appointments Module in UI view.

API calls you have to make before creating a record:

Before inserting a record into the Appointments module, it is important to know the API names of the fields and their parent modules. 

i. Use the GET - Module Metadata API to know the API name of the module. In our case, the Appointments module.

Request URL : {api-domain}/crm/v8/settings/modules

Request Method : GET

Sample Response :

 

In the API response, search for the module with "module_name": "Appointments" and check the value of the "api_name" key to get the API name of the module. This is the name you will use in all related API calls.

ii. Use the GET - Fields Metadata API and get fields metadata for the Appointments module. Here, you can find the API names of the mandatory fields along with other fields present in the Appointments module. 

Below is the API call & response for the multi-module lookup field along with other mandatory fields.

Request URL : {api-domain}/crm/v8/settings/fields?module=Appointments__s

Request Method : GET

Sample Response :

Note: The above image highlights only the key properties of the Multi-Module Lookup (MML) field from the field metadata response. The complete API response contains additional properties not shown here.

In the response:

• The multi-module lookup field is identified by the key "data_type" with the value "multi_module_lookup".
• The associated modules supported by the MML field (e.g., Contacts, Patients) are listed under the "modules" key.
• Other mandatory fields like Service Name, Appointment Name, and Appointment Start Time can be identified by "system_mandatory": true.
  

The keys of the above multi_module_lookup JSON object are explained below:

"multi_module_lookup": {     "display_label": "Appointments", // Display label of the module where the MML field is used     "api_name": "Appointments__s", // API name of the Appointments module     "modules": [ //List of modules associated with the Appointments module.          {             "api_name": "Contacts", //API name of the associated module              "module_name": "Contacts", // Display Name of the module              "id": "5725767000000002179" //Unique ID of the module         },         {             "api_name": "Patients", //API name of the associated custom module             "module_name": "Patients", //Display label of the module             "id": "5725767000006473007" //Unique module ID         }     } ] },

Note: 

• You cannot add or remove modules from the Multi-Module Lookup (MML) field using APIs. These actions are only available through the Zoho CRM UI.
• Once a module is disassociated from the MML field, existing records associated with that module will remain in the Appointments module, and you will no longer be able to associate newly created records from the disassociated module using the MML field. 
  

The remaining system-defined mandatory fields, along with their API names, are listed below.

System-defined Mandatory Field Names	System-defined Mandatory Field API Names
Service Name	Service_Name
Appointment Start Time	Appointment_Start_Time
Appointment Name	Appointment_Name
Member	Owner
Location	Location

Note: The system-defined mandatory fields can be identified by "system_mandatory": true.

Search the system-defined mandatory field names and get their API names.

With the field API names, use the following request and sample input body to create a record in the Appointments module using the Insert Records API.

Request URL : {{api-domain}}/crm/v8/Appointments__s

Request Method : POST

Request Body :

{     "data": [         {             "Appointment_Name": "General Consultation",             "Owner": {                 "name": "Patricia Boyle",                 "id": "5725767000000411001",                 "email": "patricia@zohotest.com"             },             "Appointment_Start_Time": "2025-04-15T13:00:00-07:00",             "Appointment_End_Time": "2025-04-15T13:30:00-07:00",             "Appointment_For": {                 "module": {                     "api_name": "Contacts",                     "id": "5725767000000002179"                 },                 "name": "John Doe",                 "id": "5725767000005607020"             },             "Service_Name": {                 "name": "General Check-up",                 "id": "5725767000006387029"             },             "Location": "Business Address"         }     ] }

Sample Response:

{     "data": [         {             "code": "SUCCESS",             "details": {                 "Modified_Time": "2025-05-06T20:33:42-07:00",                 "Modified_By": {                     "name": "Patricia Boyle",                     "id": "5725767000000411001"                 },                 "Created_Time": "2025-05-06T20:33:42-07:00",                 "id": "5725767000006390001", //Unique ID if the newly created record. Please note that this record ID will be used in the following API get and update operations.                 "Created_By": {                     "name": "Patricia Boyle",                     "id": "5725767000000411001"                 }             },             "message": "record added",             "status": "success"         }     ] }

Note:

Only Contacts and custom modules are supported in the Multi-Module Lookup field. If you try to associate a new record with a module that has been removed from the MML field or an unsupported module in the MML field, the following error will be thrown. 

Retrieving a Record from the Appointments Module Using the Get Records API

Request URL : {{api-domain}}/crm/v8/Appointments__s/5725767000006390001

Request Method: GET

Request Response:

{     "data": [         {             "Owner": {                 "name": "Patricia Boyle",                 "id": "5725767000000411001",                 "email": "patricia@zoho.com"             },             "$currency_symbol": "$",             "Address": null,             "Appointment_Start_Time": "2025-04-15T13:00:00-07:00",             "Cancellation_Reason": null,             "$field_states": null,             "Appointment_For": {                 "module": {                     "api_name": "Contacts",                     "id": "5725767000000002179"                 },                 "name": "John Doe",                 "id": "5725767000005607020"             },             "Rescheduled_To": null,             "$sharing_permission": "full_access",             "Reschedule_Reason": null,             "Additional_Information": null,             "Last_Activity_Time": null,             "Cancelled_Time": null,             "Cancellation_Note": null,             "Modified_By": {                 "name": "Patricia Boyle",                 "id": "5725767000000411001",                 "email": "patricia@zoho.com"             },             "Reschedule_Count": 0,             "Rescheduled_By": null,             "id": "5725767000006390001",             "Rescheduled_Time": null,             "Remind_At": null,             "Appointment_End_Time": "2025-04-15T13:30:00-07:00",             "Status": "Overdue",             "Modified_Time": "2025-05-06T20:04:38-07:00",             "Service_Name": {                 "name": "General Check-up",                 "id": "5725767000006387029"             },             "Created_Time": "2025-05-06T20:04:38-07:00",             "testing": null,             "Rescheduled_From": null,             "Cancelled_By": null,             "$editable": true,             "Appointment_Name": "General Consultation",             "Duration": 30,             "Record_Status__s": "Available",             "Created_By": {                 "name": "Patricia Boyle",                 "id": "5725767000000411001",                 "email": "patricia@zoho.com"             },             "Tag": [],             "Location": "Business Address",             "Reschedule_Note": null         }     ] }

Updating MML Field Value Using the Update Records API

Request URL : {{api-domain}}/crm/v8/Appointments__s/5725767000006390001

Request Method: PUT

Request Body:

{     "data": [         {             "Appointment_Start_Time": "2025-04-16T14:00:00-07:00", //Updating the Appointment_Start_Time             "Appointment_End_Time": "2025-04-16T14:30:00-07:00", //Updating the Appointment_End_Time             "Appointment_For": {                 "module": {                     "api_name": "Employees", //Updating a different module                     "id": "5725767000002161028"                 },                 "name": "Patrica", //A record from the Employees module                 "id": "5725767000006272001" //unique ID of the record             }         }     ] }

Multi-module Lookup Using the COQL API

Querying Inner Fields of Linked Modules within the MML Field

With the COQL API, you can query inner fields of linked modules within a Multi-Module Lookup (MML) field. This provides deeper insights into related fields data in a module. This query support is available from Zoho CRM API Version 7.

Sample Query:

{  "select_query": "select 'Appointment_For->Contacts.Lead_Source' from Appointments__s where id is not null" }

The above query retrieves the Lead Source field from the Contacts module within the Appointment_For MML field. 

Sample Response:

Querying Multi-Module Lookup Module Name

Querying the module name associated with each record in a Multi-Module Lookup (MML) field. This query support is available from Zoho CRM API Version 7.

Sample Query:

{ "select_query": "select Appointment_For.module.api_name, Appointment_For from Appointments__s where id is not null" }

The Appointment_For.module.api_name returns the module name (e.g., Contacts or Accounts) for each record linked in the Appointment_For MML field.

Sample Response:

Multi-module Lookup Using the Bulk Read API

Bulk Read API allows you to fetch a large set of data i.e., you can fetch a maximum of 2,00,000 records in a single API call. 

Specify the API name of the Appointments module in the module JSON object when making API calls. Refer to the following section for an example.

Request URL : https://www.zohoapis.com/crm/bulk/v8/read

Request Method : POST

Request Body :

{     "callback": {         "url": "https://webhook.site/7b58ff0b-b61b-4fbf-953f-1bf8b180a3c4",         "method": "post"     },     "query": {         "module": {             "api_name": "Appointments__s" //API name of the Appointments module         },         "file_type": "csv"     } }

Note: The Appointment_For field cannot be used in the criteria.

As the API is an asynchronous API, the response will not be available instantly; the bulk read job is scheduled, and the status can be checked. Once the job is completed, you will be notified in the callback URL. The records are available in a downloadable CSV file or ICS file (for events). See the Bulk Read API document to know how to view the status of the scheduled job and download the file, along with more sample requests and responses.

Sample Exported Response 

Frequently Asked Questions

1. Which modules are currently supported in the MML field?

Only Contacts and custom modules can be associated with an MML field.

2. What error is thrown if I try to associate a record with a removed or unsupported module in the MML field?

If you try to associate a record with a removed or unsupported module in an MML field, the system will throw an "INVALID_DATA" error.

3. Is the MML field available for all modules?

No, as of Zoho CRM API Version 8, the MML field is available only as a system-defined field in the Appointments module.

4. How do I get the list of modules associated with an MML field?

You can use the GET - Fields Metadata API for the Appointments module and look for the field with "data_type" : "multi_module_lookup" and check its "modules" JSON array.

5. Can I add or remove modules from a Multi-Module Lookup (MML) field via API?

Adding or removing modules in an MML field is not supported via API. These actions can only be done through the Zoho CRM UI.

6. What happens if I remove a module from an MML field?

If a module is removed from the MML through Zoho CRM UI, it can no longer be associated with new records, but existing records linked to that module will remain unaffected.

7. Is MML field supported in the Bulk Write API?

As of Zoho CRM API Version 8, the MML field is available only in the Appointments module as a system-defined field. The Appointments module is not supported in the Bulk Write API.

8. Is MML field supported in the Search API?

The MML field is not currently supported in the Search API.

We trust that this post meets your needs and is helpful. Let us know your thoughts in the comment section or reach out to us at support@zohocrm.com

Stay tuned for more insights in our upcoming Kaizen posts!

Cheers!!!

Previous Kaizen: Kaizen #188 - Building a Timer and Worklog Widget (Part 2)

Related Readings:

• Kaizen #124 - Manipulating Subform using Zoho CRM APIs
  
• Kaizen #125 Manipulating Multi-Select Lookup fields (MxN) using Zoho CRM APIs
  

• Topic Participants

• Subramanian K

  

• Andres

• Sticky Posts

• Kaizen #217 - Actions APIs : Tasks

  Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

• Kaizen #216 - Actions APIs : Email Notifications

  Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

• Kaizen #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 achieved

• Kaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script

  Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.

• Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI

  Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the

• Recent Topics

• Exporting record notes in bulk

  Hi team, Is it possible to bulk export the notes attached to a record? i.e to a CSV file or otherwise. Our use case is exporting all notes for our lead/account/Deal records. We have another system we'd like to import these notes to but I can't seem to

• Field customization

  Hi Team Good day! I am a commission agent who sell and purchase goods from vendors, while in purchasing invoices I am not able to deduct the expenses such as commission and other expenses on actual amount. Kindly help me to customize the invoice based

• vendors / customers with 2 different address and gst no

  Why can't we have option for more than one address and depending on the state option for more than 1 GST no. ? We have customers / vendors PAN india with different addresses and GST no. for different states.

• Error: Invalid Element gst_no, Invalid Element gst_treatment, Invalid Element place_of_contact

  so i am creating a new contact post request and i want add gst infomation when amount is above 50000 and if pass gst info in request body then i get this errors > Error: Invalid Element gst_no, Invalid Element gst_treatment, Invalid Element place_of_contact

• Add multiple Billing Addresses under one GST number

  My client owns multiple businesses in various locations but they all come under one GST. Is there a way to add multiple billing addresses for the same GST? Managing this by adding multiple Shipping addresses is not an option. The client wants the GST

• Zoho Mail API - Upload Attachment

  https://www.zoho.com/mail/help/api/post-upload-attachments.html I followed the steps from the API documentation and wrote a backend in JavaScript to send emails. Normal emails are sent without any problems. However, I can’t send emails with attachments.

• Unable to create custom fields for shipment order

  I'm unable to create custom fields for shipment orders, even though the custom fields are set up correctly. A request to the following endpoint: https://www.zohoapis.com/inventory/v1/settings/preferences/customfields?organization_id=${ZOHO_ORGANIZATION_ID}&entity=shipment_order

• Kaizen #202 - Answering Your Questions | Testing and Using REST APIs in Widgets

  Hello Developers! Welcome back to a fresh week of Kaizen! Thank you for your active participation in sharing feedback and queries for the 200th milestone. This week, we will look at the following queries related to widget: Widget Testing Using REST API

• Introducing the 'Send as Email' option on the Zoho Desk iOS mobile app

  Hello everyone! In the latest version(v2.10.2) of the Zoho Desk iOS app, we have brought in support for the 'Send as Email' option while creating a ticket. This feature enables you to reach out to the customers by sending outbound emails. The emails are

• Zoho Forms Not Loading on Website – DNS Resolution Error

  Dear Zoho Support Team, User ID : 20069458731 We are experiencing an issue with the Zoho Form embedded on our website (https://vitel.com.tr/satis-destek-formu/). The form is not loading, and the following error message appears in the browser: “forms.zohopublic.eu

• Data backup retention question/

  My zohocrm subscription gives me 2 full data backups per month. I have a scheduled backup configured to run twice a month. I just went to download my backup and i can't find it, it ran about 9 days ago... From what i can tell with google zoho only keeps

• Basic Apple Watch App

  Sometimes I leave my phone behind. I will get push notifications that tickets are updated etc.. It would be nice to at least view them and do a few basic functions. reassign. public reply. private comment.

• Look and Feel Uniformity

  Someone needs to go through the mobile app and match the look and feel of the web version. For example, it is global standard to highlight private notes as yellow background hue. Desk does that on web, but not on mobile. Mobile also has an odd blue icon

• Managing two books in Zoho Books

  is it possible to effectively manage two separate books within Zoho Books? My organization is considering handling accounting for two distinct subsidiaries, and we would like to understand the best way to achieve this within the Zoho Books.

• Display All Custom Buttons Without Dropdown on Record Page

  In my org's workflow we usually want to do some kind of quick action off of an individual record - i.e. of an individual contact, or individual deal. What we have always found a hindrance is the location of all custom buttons being in the drop down on

• Zoho Sales Team - Extremely Slow Response Times

  Hi everyone, Has anyone else experienced unusually slow response times from Zoho’s sales team? I sent an email last night, and it’s been nearly 24 hours with no reply. While I understand delays can happen, this seems longer than expected for a sales inquiry.

• Yodlee Bank Feeds

  I'm well aware of the many bank feed issues out there that haven't been resolved, but I'm looking for information on Rules in relation to bank feeds. U.S based, Bank of America user and prior to Yodlee all of my banking feeds and Rules worked seamlessly.

• Unable to create custom function

  Unable to create custom function - Please check the screenshot for the details HERE IS THE FUNCTION!! try { // 1. Fetch the details of the approved Bill using its ID billDetails = zoho.books.getRecordById("Bills", organization.get("organization_id"),

• Need a feature which can validate PAN from Income Tax Portal

  Hello Zoho, We need a feature which can help us validate PAN which is being entered in AR/AP Profiles to check if it is valid and display the name as per Income Tax so as to get rid of incorrect PAN into the systems. Please do the needful Thanks

• PAN - Aadhar Link Status

  Can Zohobooks also get latest PAN-Aadhar Linking Status from Income Tax Portal ?

• Canvas translation

  We want to offer our CRM system to our users in English and Dutch. However, it seems that text in our deal Canvas isn't available for translation through the translation file. The same applies to the field tooltips. They don't appear in the translation

• Are Cadences visible to anyone with Cadence permission?

  When setting up a new Cadence is it possible to restrict its use to a specific user? How can I prevent users from making modifications to existing Cadences?

• Show my cost or profit while creating estimate

  Hi, While creating estimate it becomes very important to know exact profit or purchased price of the products at one side just for our reference so we can decide whether we can offer better disc or not .

• Issue on Upload API and href image URL

  Here is my Full API Code , URL : URL: https://desk.zoho.com/api/v1/uploads/659563000000193003/content Headers* Authorization: 'Zoho-oauthtoken 1000.ed5ce2836bf5ba9b946f5ec9************88e73ff4883a3e9c58ffeb7870' orgId: 7586***** RESPONSE{ "errorCode":

• Issue when downloading a Mail Merged Zoho Writer Document as .docx

  Hi, We are using within Zoho CRM mailmerge to create documents. This results in a Zoho Writer document. When we try to download as a Microsoft Docx file we get following error: "Word experienced an error trying to open the file. Try these suggestions.

• 【Zoho CRM】ケイデンス機能のアップデート

  ユーザーの皆さま、こんにちは。コミュニティチームの中野です。 今回は「Zoho CRM アップデート情報」の中から、ケイデンス機能のアップデートをご紹介します。 ケイデンス機能の2つの強化されたことで、適用と解除のタイミングをより柔軟に管理できるようになり、 よりタイムリーで的確なコミュニケーションが実現できるようになりました。 目次： 1. ケイデンスの再開／最初からのやり直し 2. ケイデンスからのデータ解除タイミングの設定 1. ケイデンスの再開／最初からのやり直し 手動削除、完了、または適用解除条件が満たされた場合など、以前に適用解除されたデータをケイデンスに再適用できるようになりました。

• Anyone get the OpenAI API to work in Zoho Meeting?

  Has anyone been able to get the OpenAI API to work in generating meeting summaries? I have been trying, but I get an error that says "OpenAI key notes request rate exceeded. Please try again later or upgrade your open AI account." I contacted Zoho support

• Push Notifications Customization

  There is no way to customize the notifications we get. I would like to be able to get notifications based on if they are assigned directly to me, my team, my department, or perhaps tickets that match a specific criteria (a contact or account is a VIP

• Announcing Early Access to the next generation of Zoho Desk UI

  Customer service is one of the categories where efficiency and quality of service have to run in parallel, and your team's experience with their helpdesk goes a long way ensuring these aspects are uncompromised. Introducing DOT Design for Zoho Desk -

• Editing the record in report

  I have a use-case as below- User creates a assessment record by filling some fields. User assigns that record to portal user by using Assigned To dropdown (Assigned To is Users field in form with choices as customers). I have set the record owner of form

• Can we have Bills of Material Module ?

  Can we have Bills of Material Module ?

• Main Ticket Page Customization

  We do not love the ticket list page (right after clicking Tickets menu item) would like options to customize it.

• Agent Collision Missing from Mobile App

  Please add Agent Collision capabilities to the mobile app.

• Zia Sentiment and Functionality on Mobile

  Please add Zia sentiment and generative responses to the mobile app. It would be nice to see the ticket sentiment and generate a response back to a user using Zia on my iPhone

• View Account Attachments on iOS

  Please allow us to view account attachments on the mobile iOS app!

• How do I run a PnL by Sales Person?

  I am trying to run a PnL by sales person but am not seeing the option do so. All I need to know (per salesperson) is revenue, cost of goods, gross profit.

• View Contracts and Support Plans on Mobile

  We would like to be able to see contracts and support plans from the mobile app on iOS!

• App like Miro

  Hi all, is there a way to have a interactive whiteboard like in Miro? We want to visualize our processes and workflows in an easy way.

• Loan repayment Entry

  While receiving loan, i does following steps in My Zoho books. 1. Create "Loan & Advance " Account as Parent Account under Long Term Liabilities. 2. Create another account For Example "Mr. ABC's Loan as Child account under the parent account. Now: In

• Quotes module send email reverted back into 2022??

  Our Zoho CRM PLUS quotes, sales orders, invoice modules is showing us an email composer from 2022. We cannot send emails and its been a real pain. I tried clicking the new version over there but it doesnt seem to do anything. Any help is welcome. th

• Next Page