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 #198: Using Client Script for Custom Validation in Blueprint

      Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

    • Kaizen #226: Using ZRC in Client Script

      Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this

    • Kaizen #222 - Client Script Support for Notes Related List

      Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

    • 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

    • Recent Topics

    • How do I import Connected Records for a Deal?

      Can you point me to an example of the CSV file that would add related records to an existing CRM Deal? I imported a Deal, then tried importing a connected record using a unique ID that references the Deal ID, but it doesn't attach it to the Deal rec

    • File Upload Field in Zoho Forms Not Updating Existing File in Zoho CRM

      Hi everyone, I’m trying to understand the behavior of a file upload field mapped from Zoho Forms to Zoho CRM. Scenario There is a File Upload field in a Zoho CRM module. A Zoho Form also has a File Upload field, which is mapped to that CRM field. When

    • Zoho Training

      Greetings! I am trainer. My focus area is Project Management and MS Project. I have used Zoho CRM to a good extent. Though, I was interested in using ZOHO projects, as there were no live projects, I could not take it up for studies. Recently a client

    • Detailed list of scoring rules in Zoho CRM

      Good morning Zoho community, warm greetings The reason for my message today is that I have a problem with my CRM, which I will explain below: Our organization has scoring rules designed to rate our potential customers or leads in the application based

    • How to create a summary document from Projects details

      Hi, Our team is creating many projects inside Zoho Project. When closing a project, they write a summary document containing data from the projects it-self (understand project budget, customers, etc...), and editable (ie the document is either a Writer

    • Request to Recover Deleted Task List – Project ID: RIV-MOD-10722

      Hi Zoho Team, I hope this message finds you well. My Zoho task list associated with Project ID: RIV-MOD-10722 appears to have been deleted. When I clicked on the task link from the email notification, I received the following message: "Task has been deleted

    • Host in US Data Centre

      I humble apply to be registered on US Data centre

    • convert the project to templet

      i have some deployment ME product for different customer , i need to create a fixed template for use it rather then keeping creating this template every time

    • Best practices for managing Project Charters, Business Case and RAID logs within Zoho?

      Hello everyone, I’m currently refining our PMO setup within Zoho Projects and I’m curious how others are handling high-level governance documentation. We’ve been using the standardized Project Charter, Business Case and RAID frameworks from projectmanagertemplate.com

    • Resource Management System built using Zoho CRM, Creator, Projects, and People:

      In a Resource Management System built using Zoho CRM, Creator, Projects, and People: CRM Deal Closed → Creator Allocation Engine → Zoho Projects Task Assignment What is the recommended architecture to handle dynamic reassignment when: an employee goes

    • Dynamic Remaining Quantity in Lookup During Allocation

      Hi everyone, From what I understand in Zoho Creator, lookup fields only display the stored value from the source record and do not dynamically update while a form is being filled. Because of this, showing a real-time updated remaining quantity inside

    • connect zoho creator with google drive

      Hello everyone, I need to connect to a folder drive. The idea, is that google drive loads a text document with some data, I must read that text document to be able to autofill a form that I have in zoho creator with that data. I also attach PDFs and place

    • Ability to Attach Record-Specific Files Automatically in Workflow Email Templates

      Currently in Zoho CRM, email templates allow attachments to be added, but these attachments are static and remain the same for every recipient. There is no straightforward option to automatically attach a file that is stored within the specific CRM record

    • Uploaded files are not included when using "Include user submitted data" in Email Notification

      In Send Email notification workflow in Zoho Creator, there is an option called "Include user submitted data" which allows the email to contain all the form submission details. However, when this option is enabled, files or images uploaded through File

    • kanban view for client portal

      Are kanban views an option for client portals? Access to Kanban views in the client portals would solve some mobile-compliant issues I have with the UI. Kanban functions very nicely on mobile and would be a super asset for my clients and vendors as they

    • Credit Card Pre-Authorization with later Capture/Settlement

      We really enjoy the convenience of being able to pay off a customer's invoice using our Auth.Net integration with Zoho Books. Unfortunately, we can only take advantage of this feature with a small percentage of our customers as it leaves a gaping hole

    • Zoho Cliq not working on airplanes

      Hi, My team and I have been having this constant issue of cliq not working when connected to an airplane's wifi. Is there a reason for this? We have tried on different Airlines and it doesn't work on any of them. We need assistance here since we are constantly

    • Zoho Sign 2025–2026: What's new and what's next

      Hello! Every year at Zoho Sign, we work hard to make document signing and agreement execution easy for all users. This year we sat down with our head of product, Mr. Subramanian Thayumanasamy, to discuss what we delivered in 2025 and our goals for 2026.

    • Work Orders / Bundle Requests

      Zoho Inventory needs a work order / bundle request system. This record would be analogous to a purchase order in the purchasing workflow or a sales order in the sales cycle. It would be non-journaling, but it would reserve the appropriate inventory of

    • Izettle or Sumup Integration for Zoho Books.

      The Stripe & Square clearing works great in Zoho Books. Any further integrations planned in the future for Izettle or Sumup? These card processors are very common for taking payments with a card reader.

    • Train Zoho Answer Bot Based on Customer

      Hi all, Is it currently possible to mark Help Centre articles to a specific customer, and restrict the answer bot to only use relevant information if it is either marked as "General", or tagged for the specific customer in question? We currently have

    • Trying to access records in a custom module in Zoho Desk and not having luck

      I've built a custom module in Zoho Desk and am using a custom function to query the records in the module and I'm not having any luck. The only way I have found to retreive a record is by getting it by its recordID (the long zoho assigned one). The function

    • Composite items inside of composite items; bill of materials needed

      Hi Zoho and Everyone, I am evaluating whether Zoho Inventory will work for my small business. I grow and harvest herbs and spices but also get from wholesalers. I use all these items to make herbal teas, but also sell them as individual items on my Shopify store and Etsy. I discovered the composite item bundling and am wondering if I could get some assistance since there is no bill of materials: Our herbal company's best selling tea is a sleepytime tea. Sleepytime Tea can be purchased in three weights

    • ZOHO Books Smart Accounting Software for Travel Agency

      Dear Travel partner, Contact for Travel Agency Accounting Setup & Training Vansh Travel (ZOHO Books Authorised partner) Email: info@vanshtravel.com Mo: +91 98984 95155 Please find PDF   

    • 452 Mailbox delivery restricted by policy error

      We have been testing Zoho desk for about a week now and have been forwarding emails in via an Exchange Online Mail flow rule without issue until yesterday. Suddenly yesterday morning we started getting the vast majority of the emails stuck in Pending

    • Send Email reply on behalf of Agent

      Hi, When using the send email reply via the API I can set the reply on behalf of the customer by using impersonatedUserId in the header of the API call. Is there a way to do this for Agents too? I need to be able to send an email reply on behalf of an

    • Sharing Tickets to a team within a department

      Hi there, We have a need for one department to be able to share tickets to a specific team within a department, I'm wondering if this is possible? All the shared tickets are going into the 'Shared Tickets' view for the whole department but is there a

    • Removing To or CC Addresses from Desk Ticket

      I was hoping i could find a way to remove unnecessary email addresses from tickets submitted via email. For example, a customer may email the support address AND others who are in the helpdesk notification group, in either the TO or CC address. This results

    • Do not use isnull()

      Does not always return booleans. Can also return null. Never use this function. Just use var==null instead.

    • Organization wide Account and Contacts Visibility/Sharing Capabilities?

      Has anyone figured out a way to make visibility or sharing of Accounts and Contacts to be available across the entire organization without having to have every individual user edit their Sharing permissions? For our sales folks they need to be able to

    • Is there a way to configure dark mode for Campaigns emails that go out to customers?

      I've found a lot of information on how to configure dark mode for my (The user) personal Zoho workspace and email, but is there any way to edit dark mode settings on emails that we send out to customers via campaigns?  We sent out a test email the other

    • When Does WorkDrive integrate with Books?

      When Does WorkDrive integrate with Books?

    • FSM integration with Books

      Hi, I have spent a few months working with FSM and have come across a critical gap in the functionality, which I find almost shocking....either that, or I am an idiot. The lack of bi-directional sync between Books and FSM on Sales Orders/ Work Orders

    • How to close an estimate ?

      Hello, I have created estimates, and converted them to invoices to get 50% payment. Now I have 2 cases where the estimate stills shows status partially invoiced, however: 1. for one of them, project stopped half way, so the remaining part will never be

    • Power up your Kiosk Studio with Real-Time Data Capture, Client Scripts & More!

      Hello Everyone, We’re thrilled to announce a powerful set of enhancements to Kiosk Studio in Zoho CRM. These new updates give you more flexibility, faster record handling, and real-time data capture, making your Kiosk flows smarter and more efficient

    • How do you print out the invoices comments

      I have some invoices where i need to print out the comments that show when reminders and etc were sent how do we print those out in Zoho Books.

    • Unable to load a specific image

      Hi I am trying to upload an svg file, which reports that there is "a problem with the file", but does not say what sort of problem. I can't find anything which says which files are supported, so it may be it does not support svg. (which would be a real shame) The file itself will open in either Firefox or Chrome without problem. For the moment I am using a png file, which does not zoom well of course. David

    • Why does the Address field show the wrong map location even with a correct Pincode?

      I am noticing an issue with the Address field map in Zoho Creator. When I enter a city name that exists in multiple locations within the same state, the map sometimes points to the wrong area even if I have entered the correct Pincode. Currently, it seems

    • Books <-> CRM synchronisation with custom Fields

      Hello, We are synchronising Books Customers with CRM Accounts. In CRM Accounts I set up last year a "segments" multiselect field shown below In Books, I set up a custom multi-select field with the same value as in the CRM And set up the synchronisation inside Books. Want to synchronise the Books Segments with the CRM Segments, but the later doesn't exist, and another non-existing is there ?! First, I don't understand where the field Segmentation is coming from. Second, I set CRM Segmentation to sync

    • CRM x WorkDrive: We're rolling out the WorkDrive-powered file storage experience for existing users

      Release plan: Gradual rollout to customers without file storage add-ons, in this order: 1. Standalone CRM 2. CRM Plus and Zoho One DCs: All | Editions: All Available now for: - Standalone CRM accounts in Free and Standard editions without file storage

    • Next Page