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

      • QR code image is not exported in PDFs

        The new QR code field works fine when I include it in a report template and I choose the print option: https://creatorapp.zoho.com/<username>/<app_link_name>/record-print/<report_link_name>/<record_ID>/ But when I try to save the document to a .pdf file

      • Zoho Form to Zoho Form Integration

        I've created an application form that asks for references. I would like the submission of the application form to trigger a form to the reference using the email id and name entered in the first form. In the reference form that is triggered I need to

      • CRM: related table using module queries, are links possible?

        Hello. I was exploring the possibility of using a module query to get a filtered related list. For example, I'm using a Canvas custom details page and if an account has an open deal I'd like it to appear at the very beginning of the account page, with

      • 【開催報告】名古屋 ユーザー交流会 Vol.1 2025/6/6 Zohoで社内システム管理を実現するユーザー事例の共有

        ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 6/6(金)に名古屋 ユーザー交流会 Vol.1を開催しました。当日は11名の皆さまにご参加いただきました。 本投稿では、当日実施したセッションの様子と投影資料をご紹介します。会場にお越しいただけなかった方も、ぜひご覧ください。 ユーザー活用事例セッション：Zoho CRM Plusによる引合~見積~受注までのプロセス統合 日本アイリッヒ株式会社の清水裕さんに登壇いただきました。以下に一部抜粋して掲載しています。ぜひご覧ください。 セッションの後半は、清水さんの環境を投影いただき、実際の画面上で操作しながらご説明いただいたため、本記事では掲載しておりません。予めご了承ください。

      • Better reorder point functionality?

        1. How about having item reorder point warehouse level instead branch? 2. Considering committed stock and to be received quantity also as reorder point calculation? 3. Considering associated items as committed when sales order created on composite i

      • Batch tracking updates

        I applaud the Zoho team for their recent updates to batch tracking information and even though I have 'chatted' to the Zoho team, I'm still batteling to understand the reasoning on the below. We buy stock in bulk and it is received into the Bulk Warehouse.

      • Custom Button in Shipments

        Custom buttons feature is very much needed in shipments. Please work on this feature request!

      • Zoho Support is Dysfunctional & Don't Know Their Own Support Hours

        Seeking clarification on Zoho support hours and contact numbers please. We have been trying to phone Zoho support on +61 2 8066 2898 at 9:20am AEDT for the second day in a row, and gotten a message on Zoho's support line: "support is open monday through

      • What are the knowledge database limit for AnswerBot and which app its integrate?

        1) Can AnswerBot be integrated in Trainer Central? 2) Can AnswerBot learn from external websites and excel spreadsheets? 3) Is there a limit size or number of documents for the knowledge based content to train AnswerBot? Thanks

      • Reports showing 24hr days instead of business hours

        I am not sure what I am missing, I created a report to look at resolution times in business hours but it is displaying hours based on 24hr days. I have business hours set (7am-5pm) and all that functionality is working, the reports are displaying 2 days

      • Skip Pages - Zoho form

        Hi Team, I need help with skipping pages based on the below logic in Zoho form: If field number of borrowers is 1 and field number of dependants is 0 then do not show page borrower 2 and 3 If field number of borrowers is 2 and field number of dependants

      • How to print blank form and also how to use form offline

        I have created a form in PC and want to use the form in the field to gather information. Can I use the form offline in PC - in case I have no internet access? As a fail safe, I'd like to print the blank form ut just in case the PC form doesnt work for

      • Using Marketing Automation Journey to associate lead record with a campaign?

        Hello, I am trying to push people from a Marketing Automation Journey to a CRM campaign so I can track lead journeys and lead conversions however I am hitting a roadblock. When a lead hits particular scores or does specific actions in marketing automation

      • Expose FIFO COGS in Invoice API

        Currently, in the Invoice API, the line_items array contains the purchase_rate field. Unfortunately, this purchase_rate field is the Cost Price of the Item, not the FIFO cost journaled into COGS for that sale. There seems to be no current way to get the

      • Drag-and-Drop Customization Interface for Help Center in Zoho Desk

        Hi Zoho Desk Team, We hope you're doing well. We’d like to submit a feature request regarding the customization of the Help Center in Zoho Desk. 🔧 Current Limitation: At present, Help Center customization options are quite limited through the Zoho Desk

      • hide resolution from help centre

        to my surprise, i just found out that the resolution text is public in the helpcenter, even if 'notify customer' is off. is there a workaround to that? how do others deal with this? How zoho support does this and I don't think its used by Zoho in the first place. the resolution is meant to be private, not public

      • Stop selling out of stock Items.

        Hi I have been using Zohobooks for a around 8 month now. I am not involved in selling process but my staff cant stop selling product which they do not hold in stock, this is a big headache for me as physical count never matches what is shown on the books. 

      • Importing New Items to be Added to Existing Item Group

        How to use the import sheet to import new items to be added to an existing item group. The import gives me an error that the item group name already exists and won't proceed. If it's possible, how should my import spreadsheet should look like?

      • ShipStation and Zoho Inventory

        Hello, I am looking to sync zoho inventory with shipstation ZOHO INVENTORY           SHIP STATION Sales Order  ==>  create ORDERS INVOICE  <==    Shipments What exactly does BETA mean on the Shipstation connector?  This is required for me to sign-on in the next month. Thanks in advance for your efforts

      • Condolences and Prayers Following the Ahmedabad Plane Crash

        Dear Zoho Team, We were heartbroken to learn about the tragic plane crash that occurred today in Ahmedabad, as reported in the news. On behalf of our entire team, we want to extend our deepest condolences to everyone at Zoho and across India who may have

      • Zoho Developer Community Monthly Digest – May 2025

        Hello everyone, Welcome to this month’s Zoho Developer Community Digest! From fresh product insights to hands-on tech sessions and standout community threads, there's plenty here to keep your ideas flowing and your skills sharp. Be sure to explore our

      • Timesheet in project not visible to invited users.

        We are using Zoho Projects and have enabled the client portal so our clients can access both Projects and Timesheets. However, while the client can see the project, no timesheet entries are visible. How can we resolve this issue?

      • Scheduled outbound calls

        How do you mark a scheduled outbound call as complete? I see no way to change the status.

      • How to see exact clicked links in CRM from Zoho Campaigns ?

        Hi, I'm wondering how I can see the clicked links from an email sent from Campaigns when I'm in a campaign in the CRM module. I can see the number of clicks but I need the sales team to be able to see which link has been clicked by a prospect or contact.

      • Email parser rule will only parse emails with an exact match? What madness is this?

        I finally got myhead around deluge and scripting, but wondered why my parser wasn't working. (https://help.zoho.com/portal/en/community/topic/extract-11-digit-number-in-any-position-from-enail-subject) Problem: There are *zero* characters or phrases that

      • How to add a fee based on payment method

        I currently accept both ACH payments and credit card. I want to add a 3% fee to a number of my subscription plans if the customer chooses to use a credit card (and not ACH/checking). How do I do this? Is there an in-built feature, or would i have to create

      • Condolences and Prayers Following the Ahmedabad Plane Crash

        Dear Zoho Team, We were heartbroken to learn about the tragic plane crash that occurred today in Ahmedabad, as reported in the news. On behalf of our entire team, we want to extend our deepest condolences to everyone at Zoho and across India who may have

      • CRM Analytics - Elegant Comparator

        Anyone noticed a wierd thing on the Elegant Comparator on CRM... Compare Among - Time Period - Last 6 Weeks... only 5 weeks show Compare Among - Time Period - Last 5 Weeks... only 4 weeks show Compare Among - Time Period - Last 4 Weeks... only 3 weeks

      • Copy Templetes from one module to another in Zoho Books.

        Hello, I have created a Custom Module in Books for GST Invoice. I can see only 1 Invoice Templete over there. Can we clone or copy Invoices Templetes from Sales Module of Books into Customer Module.

      • Enhancements in Bookings browser extension

        Greetings from Zoho Bookings! We're here with another update to make your scheduling even quicker. We have enhanced our browser extension with three significant features: Copy slots to email Gmail integration LinkedIn integration Copy slots to email This

      • Some notes are shown as Not Synced

        I'm not sure why this happens but it's a weird little bug I noticed. I have two notes I believe that has that weird icon shown in the screenshot that shows that it's not synced even though the notes do sync properly. Manual syncing doesn't remove the

      • Power of Automation :: Auto-Color Tasks in Gantt chart based on values in Picklist field.

        Hello Everyone, A Custom function is a user-written set of code to achieve a specific requirement. Set the required conditions needed as when to trigger using the Workflow rules (be it Tasks / Project) and associate the custom function to it. Requirement:-

      • Zoho CRM record in blueprint unable to initiate any form of approval process

        My business case As a penetration testing company, we have engagements that need to follow a set path, from “to be scheduled” to “assigned to tester” to “regulatory documents sent” to “testing in progress” to “report delivered”. On this path, a particular

      • Edit Project Number?

        Hi all: We just signed up for a trial of zoho one, which includes ZoHo Projects. We've noticed there was a 'dummy project' preloaded in projects to help familiarize yourself with the software. We've created a couple of our own projects now but noticed since the dummy project was preloaded, our projects start with number 2 then 3, sequentially. Since it seems we will be keeping zoho past the trial, If we delete the dummy project, how do we get our own projects renumbered, beginning with 1? We'd like

      • Tip of the Week #57– Reply faster with saved response templates!

        Ever find yourself typing out the same email reply over and over again? It's time consuming and eats productive work hours. With shared response templates, you and your team can create pre-composed messages to quickly respond to common queries — saving

      • Connect MySQL database to Zoho sites

        Hi! Is there a way to connect a MySql database with Zoho sites. So the user input are stored in and dinamic data is fetched from the database? Regards, Mihály

      • What’s new in Zoho RPA: Cross-platform automation, OCR, and more!

        Zoho RPA is now included in Zoho One Zoho RPA is now part of the Zoho One suite, bringing unified automation to your entire business ecosystem. You can now automate UI-based tasks across Zoho apps and third-party systems too. From processing sales orders

      • New in CPQ: Create dynamic actions in Product Configurator (PC), clone PCs and Price Rules (PRs)

        Configuring product combinations just got enhanced. Zoho CRM's CPQ system now supports dynamic actions based on multiple base products. Additionally, you can now clone configurations for both Product Configurator (PC) and price rules (PRs). Dynamic actions

      • Beyond Email: #2 Connect better with Contacts

        After successfully creating a 'Welcome & Setup' event using the Calendar, Sarah is eager to invite her team members to participate. For a smoother communication experience and easy access, Sarah wants to store their information, ensuring quick reference

      • Integrate MS Teams with Zoho CRM for faster collaboration

        Availability Editions: Standard and above DCs: All Release status: This feature has been released for all users in all DCs. Help resource: Microsoft Teams integration Hello everyone, We're adding MS Teams to our lineup of CRM chat integrations—Cliq, Slack,

      • Next Page