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

      • Power of Automation :: Auto-Populate Integration Field in Projects with CRM Account Data

        Hello Everyone, A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate

      • Zoho Forms and ChatGPT - populating a field using AI.

        I have a form where I would like the user to enter a response or query, and have another field populated using AI. For example, user enters Field 1, AI populates Field 2 in response. I want to be able to wrap some additional instruction text around the

      • campo tag para api

        debo conectarme a una api de zoho inventory y ocupo tomar el campo tag para poder asi jalar el articulo que cuente con el campo correcto en tag ejemplo que tag existen carro y avion que cuando busque los articulo con tag carro arroje solo estos por mas

      • Uploading file as attachment to Zoho CRM

               Hi,   I am trying to attach a file to a Zoho CRM contact using Zoho Flow. Right now, I try to do it through the “Upload File” field in Zoho CRM (In my screenshots, it’s called Téléchargement du fichier 1).   Here is what I tried:   Case 1: Webmerge document The Flow is called “Custom Function” (see screenshot 101).   Step  1: Creating a Webmerge document (screenshot 99)   Step 2: I use “Update module entry” to upload the created file. I upload Webmerge’s “Document” in my “Téléchargemet du

      • Zia Answer Bot - Create Ticket

        Surprisingly, the current iteration of Zia will try to answer a question and unless you have "transfer to SalesIQ chat" enabled, it won't create a ticket for the user or offer them a method to create a ticket. We don't want it to create chats for us,

      • meassure leads phases

        Hi, I need to create a table to meassure the time that a lead stay in blueprint phases. the phases are first contact, second contact, lead spam, contacted, appointment. any idea? I have attached an example

      • Zoho Desk API Documentation missing a required field

        We are trying to create a section using this information. Even after preparing everything based on that page, we still get an error. The error we get is this: {"errorCode":"INVALID_DATA","message":"The data is invalid due to validation restrictions","errors":[{"fieldName":"/translations","errorType":"missing","errorMessage":""}]}

      • In the Custom Module I have 500 Records , this 500 record only want to view to the specific user only example user A ,

        In the Custom Module, I have 500 Old records that should only be visible to a specific user, for example, User A. Any new records created from today onwards should be visible to Record owner in the Custom Module. Pls help how i achive this .

      • Invoice template, how to change the text under "Notes" and "Terms and Conditions"

        In "Invoice templates", there are two text/info sections at the bottom:"Notes" and "Terms and Conditions". It is possible to change the names of these two headings, but how is it possible to change/alter the text under it. As a standard it says "Thank you for your business" under Notes - I need to change it into something different- How? Thank you.

      • How to reply to thread via API

        We have built a webapp for our customers that uses the Zoho Desk API to enable each customer to view their full list of tickets, view individual tickets and raise new tickets. The Zoho Desk API doesn't have the ability to reply to a ticket/thread. Replies

      • Sending merged mail templates for signatures fail since today

        We have ZOHO one, we use merge templates in CRM to edit in ZOHO Writer, and from there send it for signature through zoho sign. This all worked up until today, suddenly we read in the log that the merge is succesfull but the sending for signature failed.

      • Feature Request - Make Lead List Larger and Adjustable

        Hi LandingPage team, I recently started using LandingPage and I am happy to share my feedback to help improve the app. I've noticed on the Leads page, there is no option to make the columns wider. It would be great if the comlumns expanded to fit the

      • Zoho Projects - Pin Recent Projects

        Hi Projects Team, It would be great if I could "pin" projects on the Recent Projects list in Zoho Projects. We have some internal projects which we regularly have to add time and some regular client projects. It would be great if I could pin those projects

      • ZDK Error

        I get this error when trying to trigger a CRM Function from Client Script: Uncaught (in promise) ZDKError: {"code":"NOT_ACTIVE","details":{"api_name":"activate_client_from_prospect"},"message":"api is inactive for the given custom function","status":"error"}

      • "Disbursing product components in phases, monitoring them, and displaying only the final product."

        i have a product composed of multiple components, and these components will be delivered to the customer in batches. However, the final invoice should only show the finished product. How can I issue (or release) the components and track their delive

      • Followed Subtasks doesn't show up in the Subtasks Section

        I have a task assigned to me now in the same task, there's a subtask and I am added as the follower on that task Even though I am a follower I still don't see that in the subtasks section The view permission for the profile is Related It's supposed to

      • Tip #39- Strengthen account security with Multi-factor Authentication (MFA) – ‘Insider Insights’

        Securing your organization's data begins with verifying that only the correct individuals have access to it. One of the simplest yet most effective ways to accomplish this is to enable Multi-factor Authentication (MFA) within Zoho Assist. MFA introduces

      • Automate timeout chat tracking with Workflows in SalesIQ

        With our feature-packed Nova release, Workflows has become one of the most powerful tools in Zoho SalesIQ. They let you automate follow-up actions when key events occur, such as when a chat ends, a visitor leaves a bad/good rating, or a lead is updated.

      • Mass edit / Mass update products

        Hi, Is there any way to mass update or bulk edit product fields in Zoho Inventory?

      • Automatic Verification of IMAP Integration Status

        Our sales staff have their O365 email integrated with CRM, over time this integration requires re-authentication via the UI. I can manually check the integration status by accessing Settings -> Channels -> Email -> Email Sharing -> "Configuration Type"

      • Tip of the Week #68– Share and access files faster with Zoho WorkDrive extension.

        Have you ever wasted time searching for the right file to attach to your emails—or worried whether the right people could access it? Without proper sharing settings, files might end up inaccessible to teammates or, worse, visible to people who shouldn’t

      • CV-Library: The Newest Source Booster in Zoho Recruit!

        We’ve expanded your sourcing toolkit — CV-Library, one of the UK’s largest and most trusted online job boards, is now available as a Source Booster in Zoho Recruit. This gives recruiters instant access to millions of UK-based candidate profiles, all without

      • Zoho AI Translate Task as Rest API

        I cant find any docs on how to use Zoho AI Translate Task from a rest api call https://www.zoho.com/deluge/help/ai-tasks/translate.html I am working on a custom Widget and I dont think I can execute zoho deluge ai translate task from a custom widget.

      • Is there the possibility to book less than 250 customer portal users?

        If you use the Creator, which is included in Zoho ONe, you can create a customer portal and give access to a maximum of 3 external people / customers, right? On the Creator website I saw that you can add 250 users for 100€/month. However, we don't need

      • Display Parts custom fields in the Work Order

        Hello, I see that is it possible to add custom fields in the Parts module. Would it be possible to also add those custom fields in the Work Order Module under Parts? This would be very useful for customer who want to showcase more information about parts.

      • Unable to edit Saved Estimates

        We are facing issue with editing the price or discount for a saved estimate for nearly 1 week.

      • Translation Blueprint & Picklists with Custom Values

        Hello everyone, I downloaded the translation file and I'm not finding the blueprint transitions. Does this means that the transitions cannot be translated? Also, the picklist values to be translated in the document are not the same that are actually used the in module. For exemple, for my lead module, the picklist values for Lead Status are : Not-contacted, contacted, junk and lost lead. In the translation document (English to French), this is what I see: PicklistValues.Leads.Lead_Status.Contact

      • How to create a custom sales signal?

        I want to create a custom sales signal for a custom module. is it possible to create one? If anyone know please let me know

      • Only show products in offers based on lead source

        We work with several lead sources, each with their own products and different pricing. For example, one product might have two or three different prices. Sometimes, when creating a quote, the wrong product is accidentally selected. Is there a way to only

      • Narrative 7 - The importance of data sharing

        Behind the scenes of a successful ticketing system - BTS Series Narrative 7 - The importance of data sharing Definition Data sharing requires a commitment to preserving the integrity and dependability of shared data throughout its entire lifecycle. This

      • TrueSync regularly filling up my local disk

        Seems that WorkDrive's TrueSync randomly starts filling up my local hard drive space. None of the folders have been set as "Make Offline" but still it seems to randomly start making file offline. The settings of the app is so minimal and is of no real

      • Check out in Meetings

        Why there is no check out in Meetings of Zoho CRM, very difficult to track

      • Issue with Zoho Projet

        Zoho Project on all the cellphones of my customer is crashing. He has mixed brands (Samsung and Pixel). Everything is fine on website and mobile website. Could not reproduce the issue in workshop using Samsung/Pixel/iPhone Uninstallation of Zoho Project

      • SecurePass email English language issue -- please hire someone to correct the English language issues sprinkled throughout your interface

        I wrote previously about some incorrect English in your SecurePass offering. After about six months it was corrected. I have never revoked permission before today and just discovered another language mistake that was not corrected. When you revoke a SecurePass

      • Published Components

        @zoho team, Checking if we can add a password for the public links as we have non-licensed users

      • Zoho Creator customer portal users

        Hi, I'm in a Zoho One subscription with our company. I'm running a project now that involves creating a Zoho Creater application and using the Zoho Creator Customer Portal.  At most we need 25 customer portal users. In our Zoho One plan we only get 3

      • Please Enable Snippets for Agents Adding Comments

        Snippets and templates are currently enabled for agents when they use the reply functionality. There is currently no way to add a template or snippets when an agent comments. This is really weird. Our agents don't use the reply functionality, only the

      • Tip of the Week - Extracting Data from JSON Columns

        Let's say you are importing a CSV or Excel file into Zoho Analytics. What if the file contains a few columns in JSON format? This is where Zoho DataPrep, embedded right within Zoho Analytics, comes in handy. This week's tip explains how to extract data

      • Deluge UI Updates

        Are there any updates planned for the Deluge UI in Zoho Desk? It feels quite dated and lack-lustre after you've spent some time in the CRM Deluge UI.

      • Zia Agents - Follow Ups

        It would be nice to have Zia Agents do follow ups. A lot of times agents are trying to schedule things with users and they say "can we set your printer up tomorrow?" and the user never says anything. A way to have a personalized reminder to the user automatically

      • Next Page