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

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 Method : POST

Request Body :

{
    "callback": {
        "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!!!


Related Readings:


      • Recent Topics

      • Billing Management: #10 Solving Common Mistakes in Billing

        Over the past few weeks, we have explored different facets of billing, from the simplicity of traditional one-time billing to the evolving landscape of subscriptions, retainers, and usage-based models. We've unpacked how billing isn't just about sending

      • 【開催間近 - 10/17】東京 ユーザー交流会 Vol.3 参加登録 受付中！(参加無料)

        ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 10/17(金)に、東京・新橋で「東京 ユーザー交流会 Vol.3」を開催します！ ZOHOLICSよりも小規模なイベントですので、「リアル開催はちょっと緊張する…」という方も、安心してご参加いただけます✨ 当日は、初公開の事例を2つご紹介予定です！ なお、セッション映像のアーカイブ配信は予定していないため、会場にお越しいただいた方だけが、登壇者へ直接質問したり、リアルな声を聞いたりできる貴重な機会となっています。 ーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーー

      • Loading CSS Stylesheets into HTML Snippet

        Combining html/css into a single snippet can grow quite large for a UI that has a lot of functionality/styling. To keep things tidy, are we able to pull files into an html snippet using a <link> tag? If so, what are some best practices?

      • Notes Attachments

        Two things it would be nice to have the attachment size the same as the attachments sections and it would be nice to be able to attach links like you can in the attachments section. Thank you

      • Canvas: empty images

        Hello. If I add an image field like contact photo in a Canvas design, and the field is empty, there is an ugly placeholder in its place. This doesn't happen in the standard view. In the standard view, if the contact photo is empty, nothing appears in

      • Google enhanced conversions not working

        Hi guys, I've connected Zoho CRM through Google Ads interface with the goal to setup the enhanced conversion tracking in Google Ads. I have to Zoho related conversion goals which you can see in the images below: For the conversion goal above I've setup

      • MS Teams Meeting to Zoho CRM

        Has anyone figured out a good way to push MS Teams meeting info on a trigger of "meeting end" to Zoho CRM? We're looking for a way to take attendees of a meeting and meeting duration and push it into Zoho CRM after the meeting has ended. If I can just

      • Font Size 11 - Zoho CRM Email Templates

        Our company communicates with our vendors exclusively using Calibri Font Size 11, as this is the standard formatting for professional emails. Since the CRM only allows for the selection of font sizes 10 & 12, we have been unable to utilize the CRM email

      • Subforms in stateless forms

        I think the title says it all. We need to be able to add subforms to stateless forms. Currently the only workaround is to create a Form and delete each record upon submission of the form. I need to build an interface to update our inventory. Basically

      • Calling Function via REST API with API Key gives 401 using Zoho Developer

        Hi, I created a couple of functions using the one month trial of Enterprise edition, which I was able to call using the API Key method from Postman and from an external site. Now that my trial has expired, I have created the same functions in the Developer

      • How do I move a section or element from one page to another in the NEW Zoho Sites UI

        I have a section on my home page with numerous elements within it and I'd like to move the entire section to a different page on my site so I don't have to recreate it from scratch.  Is there a way for me to do that easily? I could use a quick answer on this please.

      • Zoho Projects app update: Global Web Tabs support

        Hello everyone! In the latest version(v3.10.10) of the Zoho Projects app update, we have brought in support for Global Web Tabs. You can now access the web tabs across all the projects from the Home module of the app. Please update the app to the latest

      • Export as MP4 or GIF

        Hi, Just wondering if there's a way to export/convert a presentation to an MP4 video file or even a GIF. One use case would be to use the animation functionality to create social media graphics/charts/gifs/videos. Thanks for a great tool... Rgds Jon

      • Page Layout- Horizontal Rule

        When editing the layout of, for instance, the Potentials page, is there a way to insert a horizontal rule or white space in between fields?  I'd like to keep a group of fields in the same Section, but would like to create some seperation in order to further group together certain fields within the Section.  If this is not possible, does anybody have any other suggestions on how to create this same effect?   Thank you!

      • Zoho Books will discontinue support for older browser versions soon

        Hello users, Starting from May 15, 2024, Zoho Books will no longer support the following browser versions: Browsers Version Restrictions Firefox Browser Versions older than 100 Google Chrome Versions older than 100 Microsoft Edge Versions older than 100

      • Zoho Projects - Q3 Updates | 2025

        Hello Users, The final quarter of the year 2025 has begun, and we at Zoho Projects are all set with a plan. New targets to achieve and new milestones to reach, influenced by the lasting imprint of the past quarter. 2025's Q3 saw some new features and

      • Zoho Sheet - Printing - Page Breaks and Printing Customization

        I think the title is descriptive enough in that I cannot find help documentation on a simple task of adding in page brakes for separating pages on print. Thanks

      • Issue with Trident exe file

        Hello Team, Exe Setup file It's showing harmful for user pc please check and do needful. this message for developer team. Thanks Bhargav Purohit

      • Different languages for users

        Hello, Do you plan to enable individual users to select their languages for interface? Currently language can be changed for everyone - it looks like a settings for a whole portal, which is not good when you are working internationally. Best regards,

      • Transaction Locking with the dynamic date

        Is it possible to dynamically update dates on transaction locking. We want to lock transaction x days from today

      • Unable to change sales_order status form "not_invoiced" to "invoiced"

        I am automating process of creating of invoice from sales_orders by consolidated sales_orders of each customer and creating a single invoice per customer every month. I am doing this in workflow schedule custom function where i create invoice by getting

      • Apply Vendor Credits Automatically

        We are bulk importing Vendor credits in Zoho Books!!! Is there a way to apply vendor credits automatically to the first UNPAID bill of the Vendor?

      • Apply Vendor Credit Automatically

        Hello!!! Is there a way where in we can apply vendor credits automatically on the FIRST OUTSTANDING BILL of the vendor?? We have lots of VENDOR CREDITS ISSUES mostly!!! Applying it manually is a pain for us. Would be great if we have a way to apply the

      • Need Easy Way to Update Item Prices in Bulk

        Hello Everyone, In Zoho Books, updating selling prices is taking too much time. Right now we have to either edit items one by one or do Excel export/import. It will be very useful if Zoho gives a simple option to: Select multiple items and update prices

      • Creator problem: Edit form View not displaying whole form

        I'm having problems with the form in my database. The edit view is not showing the whole form: This is how it looks in the normal view: As you can see, there is a whole section in the bottom right of the form which is not displaying in the Edit View. This means that I can't change or delete any of these fields... Anybody had a similar problem or know a solution? Any help would be appreciated.   Cheers,

      • Vendor Master Enhancements for Faster Purchase Entry

        I’d like to suggest a few features that will improve accuracy and speed during purchase voucher entry: Automated Item Tax Preference in Vendor Master Add an option to define item tax preference in the vendor master. Once set, this preference should automatically

      • Quick Item Search & Auto-suggestion for Invoices

        Hi Team, I am facing an issue while creating invoices in Zoho Books. Currently, I have to type the full item name in the correct sequence and spelling for it to appear. For example, my item name is: "Distemper Acri Silk Special White 10kg" If I type something

      • Function #53: Transaction Level Profitability for Invoices

        Hello everyone, and welcome back to our series! We have previously provided custom functions for calculating the profitability of a quote and a sales order. There may be instances where the invoice may differ from its corresponding quote or sales order.

      • Integrating Chatbot with Zoho Creator Application

        Is it possible to integrate a chatbot with a Zoho Creator application?

      • Average Costing / Weighted Average Costing

        Hello fellow maadirs. I understand Zoho Books uses FIFO method of dealing with inventory costing, but do you guys have any plans to introduce average costing? We indians need average costing. It's part of our culture. Please. I beg thee. Thanks.

      • 'Add Tax To Amount' not reflected in Invoice

        Hi Zoho Support, I'm experiencing an issue with tax calculation display in my invoice template. Despite having "Add tax to amount" box checked in the template settings, the Amount column is not showing the tax-inclusive total for line items. Current behaviour:

      • "Subject" or "Narration"in Customer Statement

        Dear Sir, While creating invoice, we are giving in "Subject" the purpose of invoice. For Example - "GST for the month of Aug 23", IT return FY 22-23", "Consultancy", Internal Audit for May 23". But this subject is not coming in Customer Statement. Only

      • A real WYSIWYG field instead of the limited rich text

        Hi to everyone A "real" WYSIWYG or HTML field that outputs good HTML code when accessed through the API would be excellent. I tried to use the rich text field, but the styling options are limited. For example, there are no heading tags (h1 to h6), and

      • Delete my store of Zoho commerce

        Hi Team, I want to delete my stores of commerce. Please help me asap. Looking for the positive response soon. Thanks Shubham Chauhan Mob: +91-9761872650

      • Delete Inactive Zoho Accounts - Access Cleanup_User Id: 60001640923

        As part of our Zoho access hygiene, we’ve reviewed and deactivated several inactive user accounts. These accounts have not been used in the past year and are no longer tied to active operations. All access rights have been revoked, and records retained

      • No feedback from Zoho Books regarding Yodlee feeds for Investec

        I reported on 6 Feb 2025 that the Bank Feeds for Investec bank via Yodlee are not working. To date there has been no resolution. You are charging us for a suite of products where the functionality does not work. Please advise how you will refund me for

      • Inappropriate Removal of Features

        It's the first with any software where I am experiencing that an existing customer has some of his exiting features removed. Moreover, new Zoho One users are paying less than us. Is this going to be Zoho's "normal behaviour". If so, it is going to be

      • Filtering report embeded in page

        Right now we are using a page variable to filter a report on a page. However, it being a page variable makes it reset if you go to another report/form, we want the filter to be kept the same. I tried using an application variable according to zoho you

      • Export Invoices to XML file

        Namaste! ZOHO suite of Apps is awesome and we as Partner, would like to use and implement the app´s from the Financial suite like ZOHO Invoice, but, in Portugal, we can only use certified Invoice Software and for this reason, we need to develop/customize on top of ZOHO Invoice to create an XML file with specific information and after this, go to the government and certified the software. As soon as we have for example, ZOHO CRM integrated with ZOHO Invoice up and running, our business opportunities

      • Zia summarizes your IM bot chats in real time

        Hello everyone! Let's say you’re an agent taking over a chat where a customer was booking a flight through a bot on WhatsApp. They've already shared key details, like their destination, travel date, and number of passengers. You need to understand the

      • Next Page