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

      • Problem with Schedule Email parameters in "Send Reply to an Email" API

        Hello, This is my Json script: { "fromAddress": "test@gmail.com", "toAddress": "{{8.fromAddress}}", "subject": "{{8.subject}}", "content": "{{4.result}}", "action": "reply", "isSchedule": true, "scheduleType": 6, "timeZone": "Europe/Lisbon", "scheduleTime":

      • What's New? - May 2025 | Zoho Backstage

        Hi everyone, A May-zing month for you! As summer rolls in and event season picks up the pace, we’ve been working on a set of updates in Zoho Backstage to help make your day-to-day life a little easier. This month’s improvements are all about tackling

      • Integrate Zia AI into Zobot with Support for Hebrew and Bot Context

        Dear Zoho SalesIQ Team, Greetings. We would like to submit a feature request that would significantly enhance the functionality and intelligence of Zobot: native integration of Zia AI into Zobot scripts and blocks—with full support for Hebrew language

      • Mail Merge: Need Transparent Background for Signatures

        I'm using ZohoCRM and Zoho sign to send documents to customers to sign. We use zohoCRM's "Mail merge" option to create the templates. The problem is that those "Signature" fields have a solid white background so it looks like a stamp on the page instead

      • Zoho Flows

        Basically I can't build a connection that works between Excel on OneDrive and Zoho. I wanted to have 1 flow checking on a row added to an excel file and then intiate an import of that row. I'm doing that manually now and thought that this could be automated.

      • Zoho time tracking with automated screenshots

        Time tracking option with automated screen shots would be an exeptuonally good feature, any plans to develop something like that?

      • Sharing my portal URL with clients outside the project

        Hi I need help making my project public for anyone to check on my task. I'm a freelance artist and I use trello to keep track on my client's projects however I wanted to do an upgrade. Went on here and so far I'm loving it. However, I'm having an issue sharing my url to those to see progress. They said they needed an account to access my project. How do I fix this? Without them needing an account.

      • Zoho Campaigns Forms not Responsive on Website

        I have a mobile responsive Zoho Sites website and when I add a Zoho Campaigns form, it is not responsive. I have used the website code and ensured that the 'responsive' checkbox is selected. But, the form is not responsive to mobile. I have attached a

      • Oldest mail on top?

        I am old, and probably missing something simple, but how do I flip my zoho mail so oldest mail is on top?  Thanks in advance, and a HUGE thank you to the entire ZOHO team.  You just keep getting better!

      • Desk API to add or change commenterId to a comment

        Please let me know how to add comments on tickets for different agents using the API. When adding a comment it will take commenterId but then ignores that and used the API agentId. Did not see in API docs which values are readonly. I pleased to see commentedTime worked for past times. Regards, Glenn

      • How send a ticket attachment using the Sendreply API in Zoho Desk

        API document references : you make use of the Upload file API and gather the attachment ID. This ID is be passed with the Send email Reply API to deliver responses with the attachment intact. Code template is as below: // ORGID ORGID = "XXXXXXX"; // Masked

      • First Insight - Find your Fields

        The Wheels of Ticketing - Desk Stories Find your Fields What are fields? Fields are crucial in ticketing modules that capture information about Tickets, Customers, Organizations, Products, and more. Depending on the kind of data being stored, users can

      • Automation#30: Auto-Update Time Entry to the Nearest 5 Minutes

        Hello Everyone, Time tracking is a feature in Zoho Desk to help businesses stay organized and efficient. For Zylker Techfix, this feature has helped to track the duration of gadget services to generate accurate bills. However, Zylker Techfix faced a unique

      • Email adding to existing ticket

        hello Is there some syntax i can add e.g. to the subject line / body of my email that when it reaches the Zoho portal will add the request to an existing ticket. e.g {123} Currently if i have an open ticket and a customer emails me direct, i then forward

      • How to define different shift timings for each weekday in Zoho People?

        Hi everyone, We’re using Zoho People for attendance tracking and need to configure a standard 39-hour workweek that is structured like this: Monday to Thursday: 8 hours per day Friday: 7 hours Currently, our service provider has set up the workweek as

      • add two date range

        Hi, How can I add two date range selections to compare two different column values in a single pivot view? I have attached a snap for your reference.

      • Announcing new features in Trident for Windows (v.1.26.5.0)

        Hello Community, Trident for Windows is here with exciting new features to elevate your email communication and enhance productivity. Let’s dive into what’s new! Open .eml files in Trident. You can now open .eml files directly using Trident. This makes

      • Adjust The max character in Specification Field

        Is there another way to adjust the maximum character limit for the Specifications field in Zoho Commerce? I need to accept responses with fewer than 200 characters.

      • Customize the Sign In And Sign Up in Zoho Commerce

        Is there another way to customize the Sign In and Sign Up in website Zoho Commerce like this i want to customize to edit it like change the "Sign In" word into "Login Zoho Commerce" it is possible or other way to do that?

      • Territories : Deluge and APIs

        I am trying to work out how to filter a deluge query by territory eg "SELECT Total_Amount, Stage, Closing_Date, Created_Time, Deal_Name FROM Deals WHERE Stage in (" + varBaseCriteria + ") AND Territory = 'Territory1'" The problem being that Territory

      • Tidying up messes file system on Site

        I'm been given access to a new site that's been managed by several different people over the years, each with different ways of managing images and files. If I move an image from one folder to another, it shows a missing image icon on the site's page.

      • Move Archive Button in Zoho Mail to Main Toolbar?

        Is there a way to add the Archive Button to this tool bar so I don't have to click the three dots every time?

      • Introducing Bigin 360: Our new pricing edition with increased feature limits and pre-installed toppings

        Dear Biginners Club, Today, we're pleased to launch a brand-new pricing edition called Bigin 360, our highest pricing edition that will sit on top of Express and Premier editions. It's been over four years since our launch, and we're receiving some great

      • URL field display value

        Is it possible to give a URL stored in a project a display value, rather than showing the whole url? I have a lot of projects connected to issues filed on a separate site, each with a distinct URL. For example: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=40000

      • need payment link excl. TDS Amount.

        Dear Team Zoho, Kindly generate a payment link excluding TDS amount. So that TDS can be submitted through portal. Thanks & Regards, Arijit S.

      • CRM is very slow now

        CRM is very slow now. Plz check ASAP

      • Access error when running invokeurl

        Hi, I'm running the following code: string standalone.test_api() { LoroToken=zoho.crm.getOrgVariable("LoroToken"); info "LoroToken:"+ LoroToken; headersMap = Map(); headersMap.put("Authorization", "Bearer "+LoroToken ); headersMap.put("Content-Type",

      • Disable Column Freeze in PWA View but Keep It on Desktop — Zoho Creator Reports

        Zoho Creator offers a useful feature to freeze up to two columns in a report view, which works well on desktops. However, our users access the app on both laptops and mobile devices, and freezing columns makes reports nearly unusable on smaller screens.

      • How do I add more space to a note in ‘draw’?

        I’m taking handwritten notes using the draw note, but I don’t seem to be able to scroll down to get more room on the page. How do I make more room to take notes?

      • Overtime per week vs. per day

        In the United States 90% of the states calculate overtime as working more than 40 hours per week. It appears that Zoho People can only calculate overtime per day.  How do we fix this? Here is an example: Mon      8 hours Tues      7 hours Wed      9 hours Thur      8 hours Fri            8 hours -----       Total      40 hours (no overtime) However, Zoho people says 1 hours of overtime because the employee worked 9 hours on Wednesday. Maybe I have something setup wrong in Zoho People?  

      • Add Hebrew Language Support in SalesIQ Idle Chat Handling and Reminders

        Dear Zoho SalesIQ Team, Greetings. We would like to request the addition of Hebrew language support in the Idle Chat Handling and Reminders functionality within Zoho SalesIQ. 🗣️ Background & Use Case Currently, we have successfully configured our Zobot

      • notebook synchronization - problem

        Good afternoon, Since yesterday when trying to create a new notebook, it does not let me and when creating the notes they are not synchronized with the cloud, I think the error may be with the encryption of images because in the pages appears the image

      • Notebook 3.5.0 -- Sort order Name A-Z not working

        Just updated to Notebook 3.5.0 on Windows 10. Sort order by Name, A to Z is backwards, like Z to A. Selecting Z to A still works as expected.

      • Stay organized with chat-to-ticket timers

        Hi there! Ever lost track of a customer’s message? Or found yourself scrolling through long chat threads trying to figure out what’s what? Setting up a chat-to-ticket timer can help. It decides when a reply should stay in the old ticket or create a new

      • New notecards not syncing across devices

        Hi, I'm having the same problem where my notes are not syncing from my Android to my laptop. Please help

      • Please add custom sort in Windows ver. of Notebook!

        Dear Zoho, I love the custom sort (drag and order notes) in the Android version of Notebook, but when I sync onto the Notebook on Windows, the note orders all get messed up because it doesn't support custom sorting yet. This makes it impossible to do

      • Formula to return string "WK 26 - 6.2.25 - 6.8.25

        Here's what I've got but syntatic failure: if(not(isnull(${Deals.GS_Due})), "Week " + Tostring(ceil(dayofyear(${Deals.GS_Due}) / 7)) + " - " + Tostring(month(${Deals.GS_Due})) + "." + Tostring(day(${Deals.GS_Due})) + "." + Tostring(year(${Deals.GS_Due}))

      • Introducing LeadChain in Bigin to sync leads from Social Ads easily

        We're excited to introduce a new topping in Bigin called LeadChain by Zoho Social. LeadChain instantly syncs lead information from social media lead ads to Bigin, making it easier to turn them into customers. It also helps you send conversion data back

      • Templates Access

        There should be an option to grant users access to templates but not allow them to edit/delete templates. In setup there is only one tick option for templates. This will give any user access to view as well as delete/edit. This doesnt make sense as they

      • Generate a Zoho Sign link

        From time to time I get a response "I never received your you e-document for electronic signature" is there a way to generate a Zoho Sign link to share.

      • Next Page