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:


    • 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

    • ranking by drag the choices instead of rank by number

      is the option of draging the choice is available instead of selecting the ranking number for each choice?

    • TASKS - Dashboard to show ALL Tasks from ALL apps.

      The Unified Tasks View is useless without the other main zoho apps (Desk, Books & even FSM now) We need to see all our tasks under on pane of glass. The Zoho developers are out of touch with real business workflows. So how it was designed they want us

    • Function #13: Transaction level profitability

      In Zoho Books, the Profit & Loss report provides valuable insights into the overall profitability of your business, indicating whether you have made a profit or incurred a loss. However, there may be occasions when you wish to assess whether a specific

    • Zoho CRM with Sap Business One

      I need information about integration CRM with Sap BO, thank.

    • Allow bill to nest multiple projects

      A bill (purchase) is more often than not used across multiple projects and this functionality is missing and very urgently needed for accurate reporting of purchases across projects

    • How can I change iOS display setting at night?

      It seems like at night the two light daytime settings themes (white with blue on top or just white) are not available and I am forced to choose among a few other colours that I really don’t want, I.e., black, blue or orange. Is there a way for me to always

    • Celebrate WWW day with Zoho Desk

      Let's recall the times when we learned 'WWW' stands for World Wide Web. Whether you like to call it wuh-wuh-wuh or double-u double-u double-u, or World Wide Web, we all owe a lot to this groundbreaking invention that reshaped how we connect, communicate,

    • The power of camaraderie

      In the days before the internet boom, conversations happened face-to-face or over the phone. Phone calls were precious; every minute counted, and every word mattered. We looked forward to those moments of real connection. Even today, nothing quite matches

    • Message Content is missing/invalid fault

      We cannot create a complete template over zoho. Some features - like button adding - is missing. The templates are created on Zoho and edited on Meta to solve the problem. But still then, some features cannot be used and the message returns this failure

    • Können bereits gesendete Kampagnen im Nachhinein einer Mailing-Liste zugeordnet werden, ohne dass die Kampagne erneut versendet wird?

      Wir haben unsere älteren Kampagnen in Campaigns über Kontaktkategorien versendet. Dann haben wir umgestellt auf Mailing-Listen, damit alte Kampagnen auch in einem Archiv aufgerufen werden können. Jetzt ist die Frage, ob die Kampagnen, die über die Kategorieauswahl

    • Newsletter Templates Are Not Mobile Responsive

      Hi, I've already submitted this request to ZOHO once this morning, but for some reason your system logged me out, wouldn't accept my username/password login, and isn't showing any evidence that I've submitted this issue. So here we go again... I am under the impression that your newsletter templates are supposed to be mobile optimised: https://www.zoho.com/campaigns/blog/responsive-email-marketing.html This is clearly not the case, as the last 2 newsletters I've created in Campaigns look perfect

    • Digest Juillet - Un résumé de ce qui s'est passé le mois dernier sur Community

      Bonjour à toutes et à tous, Zoom sur les nouveautés de juillet dernier au sein de Zoho Community France. Zoho Commerce vous propose une expérience améliorée grâce à sa nouvelle interface ergonomique et à ses fonctionnalités avancées, conçues pour faciliter

    • 100 Rows in a Subform is too limited

      We have a custom Module in CRM called Price Sheets, when we get a PO from a client we add the items from the PO to it and then check with our vendors for pricing and add our margin etc And after it is complete we have setup custom scripts to create a

    • Uninstall unattended agent

      Hello, I'm testing many use case before we purchase assist for our remote support. While we are testing what is the proper way to uninstall agent?  I did uninstall from systray, from windows control panel but still ZohoURservice is running. How can I uninstall client side?

    • Zoho Commerce Down?

      Is anyone else's storefront down at the moment? Ours has been down for at lease an hour.

    • Zoho Projects iOS app update: Dashboard widget on the home screen

      Hello everyone! We are excited to introduce the 'Dashboard' widget in the latest version(v3.10.8) of the Zoho Projects iOS app. Dashboard widgets allow you to view the project progress visually without having to open the app. The widget enables you to

    • Idea: Workflow Rule Trigger Only When Subform Row Is Updated (Thanks to New Inline Row Feature)

      Hi Zoho team and community, With the recent update to Zoho CRM, we can now add or delete rows inside subforms without entering edit mode, using the inline Add row button. This is a fantastic improvement for user experience — seamless, fast, and efficient.

    • Auto add new section based on document choices

      Hi team, I'm wondering if the below is a possilibity within Zoho sign. We have an application process to become a customer of ours, we currently use Zoho Sign to manage this application and this works quite well. However, if the customer indicates 'YES'

    • Change rate after xxxx kilometers

      Is there a way to change the miileage rate after a certain mileage. After 5000 kilometers, we want the rate to automaticly change. Thank !

    • Subform Entry Limit from a Subform Field (A different Subform on the same Form)

      Hi, I would like to be able to use a Subform 1 Field as the Dynamic Entry Limit for Subform 2. Even better would be able to use some code with the values, so for example using the Subform 1 Qty Field as the Max Entry limit for Subform 2, BUT only the

    • Slow Zobot response time

      Hi, We launched the Zobot on our site to sit along with the regular Live Chat but had to take the Zobot down as the response time was very slow. The bot was slow to begin then once the chat had been initiated the response was very slow. The bot typing

    • how to show data of 3 table in pivot

      Based on engineer name i want to get the data from 3 different tables like Service , amc, installation , but Every table contain Engineer name As Common , based that from the service table i want to take service amount , and count of service based on

    • Custom Status for Purchase Orders

      Currently Zoho books has functionality to create custom statuses for Sales Orders. Can this be extended to include custom status for purchase orders as well? It was a great decision to add this functionality to sales orders. Our use case is for tracking

    • Ask the Experts 22: Scale up your customer support with integrations & extensibility

      Hello everyone! The foundation is set. Build the beams. Raise the pillars. Set the walls. The Zoho Desk architecture stands tall. Let's discuss integration within Zoho Desk, extensions from the Marketplace, creating connections between Zoho Desk and other

    • Is there no way to duplicate an entire workflow or even custom function across multiple departments?

      Is there no way to duplicate an entire workflow or even a custom function from one department to other departments, like it is done for field duplication from one department layout to other department layouts?

    • Automated reply on any new ticket raised by customer

      Hi ZohoDesk team, Can we set up an automation so that whenever a new ticket is created against our support email; ZohoDesk immediately sends our standard acknowledgement, including the expected TAT for resolution? If that’s possible, could you share the

    • Zoho equipment rental - just like Booqable

      Hi Zoho Team, is it possible to create a module or a system like booqable? our business starts renting our IT equipment assets that have been recently used for Events and Projects, we are having ZOHO books so its easy to integrate if you create one. Booqable

    • Profit Margin Scheme

      I'm a tourism company operating in the aviation and outbound tourism sectors. Typically, taxes are 0% as our operations are outside the country. However, the state has now imposed a tax on the profit margin. This means if the selling price of an airline

    • Visibility and Enforcement for Outdated Plug Parameters in Zobot Canvas

      Dear Zoho SalesIQ Team, Greetings, We’d like to suggest an important usability and quality improvement for working with Plugs inside Zobot. Current Behavior: When we update the code of an existing Plug, any Zobot card using that Plug requires manual resaving.

    • Announcement: Zoho DataPrep to Deprecate Password-Only Authentication for Snowflake Connections on July 31, 2025

      As part of our ongoing commitment to security and in alignment with Snowflake's pledge to the Cybersecurity and Infrastructure Security Agency (CISA) Secure by Design initiative, Zoho DataPrep will no longer support single-factor password authentication.

    • The same Contact associated to multiple Companies - Deals

      Hi, I would like to know if there is an option to associate the same contact with multiple companies (two or more) deals, using the same contact details for all. This is because we have contacts who are linked to different companies or branches of the

    • Text on Zoho Sign confirmation dialouge is very small compared to text used everywhere else on Zoho Sign.

      I've reported multiple times through Zoho's support email that the text on this notification is very small in contrast to all the other text on the Zoho Sign app. I think it's a bug and it just needs the font size to be increased. It's very minor but

    • Wise integration in Zoho Books

      Hi, it is now time for zoho books to support Wise.com integration for payment links. Wise has launched credit card payments, now about 0.5% cheaper than Stripe. Also their bank payments are much much cheaper than credit cards. Its time for books team

    • Error Message: None of the rows can be imported

      I have been using zoho sheets to download my CSV file for about 2 years now, this month, October 2021, for some reason when I download it to upload to zoho books I get a message saying "None of the rows can be imported". I have been using the same process,

    • Invalid Element place_of_contact, Invalid Element gst_no, Invalid Element gst_treatment

      so this is the body contact_name: orderData.customerName, company_name: orderData.customerName, email: orderData.email, contact_type: 'customer', currency_code: 'INR', gst_treatment: 'business_gst', gst_no: 'i using proper gst no i just removed it from

    • Not able to item an item to non taxable via api, despite sending is_taxable as false

      Hi everyone, I'm trying to update an item via books api and even when sending is_taxable as false, the item still shows Taxable in zoho, I get no errors as well when I update, any help appreciated in this!

    • Collection & Payment Mapping Automation

      We book Sales Invoices and Purchase Invoices against Same Projects. Both Sales Invoices & Purchase Invoices can have one or multiple Projects mentioning the Project ID. We prefer to Make vendor Payments Once we have received The Collections from Clients

    • Nested Sub-forms (Subform within subform)

      Hi Team, Whether there is any possibilities to add sub-form with in another sub-form like Main Form       -> Sub form A             ->Sub form B If we tried this, only one level of sub form only working.  Any one having any idea about this? Thanks Selvamuthukumar R

    • Restore Trashed Records Anytime Within 30 Days

      Access the recycle bin from the Data Administration tab under the settings page in Zoho Projects, which gives better control over the trashed data. When records like projects, phases, task lists, tasks, issues, or project templates are trashed, they are

    • Avoiding Inventory Duplication When Creating Bills for Previously Added Stock

      I had created several items in Zoho Books and manually added their initial stock at the time of item creation. However, I did not record the purchase cost against those items during that process. Now, I would like to create Purchase Orders and convert

    • Next Page