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

      • What's wrong with this deluge code to create a Bill?

        I know that all the data in the map is correct. The line items are pulled directly from a purchase order. // Add the purchase order ID to the bill billPOIds.add(poID); // Retrieve and merge the line items poLineItems = purchaseOrder.get("line_items");

      • 2 Ideas, Clone timesheet entry from monthly view and Notes in Weekly view

        While i love timekeeping I am finding some things slow me down.  Slow to the point of considering writing my own API call to do this. It would be so useful to be able to clone a timesheet entry from the monthly view.  It is somewhat painful to have to

      • Zoho Workdrive API call to find public external Link for a Folder

        Hi all, I can create new external share links for a WD Folder using this API call https://workdrive.zoho.com.au/api/v1/links . This works fine, however if there is already an external link created for a given folder, trying to create a new one fails (which

      • Converting Sales Order to Purchase Order

        Hi All, Firstly, this code works to convert a sales order(SO) to a purchase order (PO) via a button, however I am running into an issue when I convert the SO where the values from the line items are not pulled across from the SO to the PO. The ones in

      • Accessing and Using Formula Field

        Hi There, I created a formula field called 'Day of the Week' in the Leads module that takes the record created time and transforms it into the day of the week. The formula field returns the correct values. However, I am unable to find or use the field

      • 🇺🇸 🇨🇦 🇲🇽 Ask the Experts: A Live Q&A Session

        Session Closed Thank you to everyone who participated in this Ask the Experts session! Your questions, insights, and engagement made it a valuable discussion for the entire Zoho Recruit community. The comment section is now closed, but feel free to browse

      • Request For Quotation (RFQ) module

        Hello, Do you have any plans to implement a RFQ module in to ZOHO Inventory? I would like to chose items that I require a price for, select a number of different suppliers to e-mail and have them submit there pricing online. I would then like to see a

      • Ability to Append or Prepend specific signer name field to all documents in an envelope

        We use templates regularly and have a need to be able to rename the individual pdf documents contained in an envelope, such that a signer's name is appended or prepended (e.g. Form1 - SignerName). This is critical for us, because of how we process documents

      • Export an email as an HTML file?

        How do we export an email in Zoho Marketing Automation as an HTML file? We have an advertising partner that needs our campaign email as an HTML file. We can't find any way to do this. If this is not possible, please explain why. It doesn't make sense

      • Function #30: Display list of associated PO on SO details screen

        Hello everyone, welcome back to our series! Imagine having the ability to effortlessly access and view details of all purchase orders linked to a sales order directly from the sales order itself. Well, today's script is designed to do just that for you.

      • Custom Print Button in Page/Stateless Form

        [Zoho Creator] Unable to Add Custom Print Button to Page or Stateless Form We need the ability to add a custom print button on a page or stateless form in Zoho Creator to print a templated or formatted output (e.g., appointment confirmation, summary slip).

      • Page Variable Not Passed from Report to Form

        [Zoho Creator] Page Variable (Resource) Not Passed from Report to Form in Appointment Module We are facing a limitation in our Appointment Module related to the handling of page-level variables. We are using a page variable to select a resource, which

      • Creating Layout Rule With Formula Field

        By The Grace Of G-D. Hi, I see that i cannot use Layout Rules to show/hide Formula Fields. Is that something you plan on adding sometime soon?

      • Combine / merge multiple invoices into master

        Good morning Zoho! Upon looking for a solution for my issue, I found many that had my similar problem...dating 13 years ago! Please, any updates on this? Merging multiple invoices on a Master Invoice would alleviate all the extra work of resending and

      • Free Webinar Alert! Productivity Hacks that you don't want to miss on June 24

        Hello Zoho Community! Want to work smarter and get more done with Zoho Mail? We’re here to help! Join our interactive webinar to explore powerful Zoho Mail features that can boost your productivity. Watch live demos, learn helpful tips, and take part

      • Web Clipper cannot save to collections

        With the recent update that added collections, i am unable to use the web clipper to save to a collection

      • sort by name is always z to a

        I typically keep my notes in alphabetical order. Suddenly they are all backwards - z to a. They stay that way whether I select a to z or z to a. Is there a way to fix this?

      • Project Management Bulletin: June, 2025

        Our project management suite's representatives have been busy socializing with global customers in the USA (Zoholics) and Australia (roadshows). We also had multiple stop overs at our customer’s establishments and were glad to see the efficiency our products

      • Agenda For Zoholics Benelux & Nordics 2025

        Dear Zoho Benelux community, We are pleased to announce the agenda for Zoholics Benelux & Nordics 2025 on September 23-24 at NBC Congrescentrum in Nieuwegein. The topics of the presentations are: Zoho innovations in the region and worldwide The introduction

      • How to query Deal "Stage" "Is Open" in Analytics SQL?

        How do I query this "field" in Analytics? What is going on? It seems like there is another 'mapping' somewhere but that it is inaccessible with raw sql??? If I query "Stage" Like '%Won%' I get a wildly different number than I do when I manually filter

      • Enhanced Candidate Portal: Now Featuring Federated Login, Passwordless Access & MFA

        You can now enhance your Candidate Portal experience with Federated Login, Password less Sign-in and Multi-Factor Authentication (MFA). These features offer greater flexibility and control—allowing seamless sign-ins through trusted platforms and adding

      • Custom View and Custom Fields

        Hi We have custom fields that we need in the Sales\Customer module and we would like to have the fields available to view in the Bills module so that we can add them to a custom view, is that possible? That way we can look at the Bills screen to see what

      • Can I write a check in Zoho Books with no associated bill?

        This currently does not seem possible, and I have a client that desperately needs this function if I am able to convert them with Quickbooks. Thank you in advance for your reply. 

      • Automation#35 : Auto-Add Comments under the Owner's Name in Tickets via Macros

        Hello Everyone, This week's custom function provides simple steps to configure a Macro for adding comments to tickets with the name of the Comment owner. When managing tickets, you can use the Comment feature to communicate internally with your team and

      • Subfrom Changes are NOT included in Audit Logs and Timeline

        In the Timeline the subform changes are not tracked We have an important custom module for Recording Pricing Information It has a subfrom, now if Changes are made to the subform fields they are not shown in the timeline, ONLY the aggregated fields This

      • Tracking Emails sent through Outlook

        All of our sales team have their Outlook 365 accounts setup with IMAP integration. We're trying to track their email activity that occurs outside the CRM. I can see the email exchanges between the sales people and the clients in the contact module. But

      • Changing Link Color

        When I create a link from a block of text, the text color changes to a color i do not want. After scrolling through the CSS and HTML files I cannot find the setting for the link color. Changing the link color word by word seems inefficient and must be a setting somewhere? Greg Aanes 2109 Queen Street Bellingha WA USA

      • Content Management System

        Is there any plan to develop a CMS application that allows us to manage all of the ZOHO services such as Writer, Sheet, and Planner? Besides that, it would be nice to manage the files and logs of WebNMS using SOA. Otherwise i'll try to make it. Thanks, Takash F

      • How do I pause or halt a running campaign?

        Hi, I set up an A/B campaign - and after testing, scheduled the campaign, I noticed an error in the subject line and had to pause or halt the campaign 'mid-flight' - could not find this, and the only option was to delete the entire campaign to halt the send (it was an emergency). Is there a campaign Pause or Stop function/button? I could not find it - am I missing something? (Thank you for your help  - I searched the resources and could not find an answer)

      • Contact Segments with multiple CRM modules

        Hello, We have a somewhat unique setup in our system involving various components: Contacts, Accounts, Deals, and a couple of custom modules named Properties and Audit Logs. We're looking to implement a notification system via SMS and Email specifically

      • Cannot reorder fields in Page Layout in Expenses and Purchase Requests

        It is very inconvenient that the custom fields in Page Layout cannot be re-ordered. The only way is to remove the fields and re-create them; however, it is impractical. This would affect the reports and dashboards we are having. Not able to re-order the

      • Having issues with creator, flow and calendar

        So I have made a creator app when engineer puts in the date and time for when they are going to out on site , this then passes the calendar data to flow and then should populate the inputed data to the calendar. So If use${system.zf_current_date_time}.

      • Problem when forwarding emails

        When I want to forward an email received through Zoho, the layout changes: Buttons are cut Pictures change size Text changes alignment (left/right/center) Is this a common problem in Zoho? Thank you, Suzannah 

      • View Audit Trail field

        The Audit Trail feature is great, but its data is only available to admin users. It would be really great to have a system field "Audit trail" that we can add to the detailed view of a record. This would allow supervisors, directors and etc. to quickly track what changes have been done by whom for each record. It is a current feature from a client of mine and while it's probably possible to hard code it, since this data is already available in Zoho, I would be surprised to hear how hard it would

      • Recuring bills payments

        I've entered recuring bills that are auto drafted from my account monthly. Can I set up the recuring payment or do I continue to manually do it monthly?

      • Automatically assign Contact Roles to a Deal

        Hi guys, Is there a way to assign multiple Contact Roles to a Deal via a workflow or similar? Thanks

      • on submit of creator form then record is create in Zoho crm purchase module then on automatically task want to create in the crm

        on submit of creator form then record is create in Zoho crm purchase module then on automatically task want to create in the crm

      • Zoho CRM Webinar – Automate everything across Customer Journeys in CommandCenter 2.0

        How efficient is your current CRM automation setup? As customer journeys become more dynamic, it's common for data and actions to get scattered across teams and modules. This leads to broken processes and inconsistent customer experiences—especially across

      • Changing employees email address

        How do I change an employee's email address? I am an administrator on the account but it says that I am "not allowed" to do it?

      • MULTI-SELECT LOOKUP - MAIL TEMPLATE

        Dear all how are you? We need to insert data from MULTI-SELECT LOOKUP in a email template, but I can't do that, when I'm creating the template I can't find the field to insert it. is there any solution? PVU

      • Next Page