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

      • Enhance Zoho One Conditional Assignment to Fully Reassign App Settings When Changing Departments

        Hi Zoho Team, We’d like to submit a feature request regarding the current behavior of Zoho One’s conditional assignment logic when moving a user between departments. 🔧 Current Limitation As it stands, Zoho One’s conditional assignment does not remove

      • Category to Alert

        Hi I am looking for help on how to solve an issue. We use the Category field for all items. We also use Composite Items. We would like to create an email alert when a Sales Order is created, however it would need to look at the Item to identify the category

      • Validation Rule (Date)

        Hi There,  Can any anyone help me with the validation rule? I'm trying to fire a rule whereby the End Date cannot be before Start Date.  Any takers?  Manoj Nair

      • Beyond Email: #3 Organize effortlessly with Bookmarks

        With her team’s details now neatly saved under Contacts, Sarah is feeling more settled in Zoho Mail. As she begins exploring her new workspace, she remembers the collection of useful links she has saved on her browser—project trackers, client portals,

      • Notification based on created/updated sales order that contain certain line items.

        Hi, I am finding the workflows within Books somewhat difficult to setup, so I am thinking that a custom function may be the best way to go about this. I want to be able to send a notification to a team member that any sales order that has been created

      • Drawings in forms

        I do a lot of drawings during my consultations and I’d like to add  body maps or stencils that I can draw on in different colours and add explanations etc. I need to be able to erase mistakes etc. Ideally in a form that I can prepopulate with client details and a few questions/ client signature and then save as a form. is this currently possible? if not, is it in the pipeline? thanks, Dennis

      • How can I populate dropdown data with information from another source or app?

        I want to maintain a list of items in another app (say in excel or another database) and sync those as items in a drop down menu, instead of copy pasting to import. Is this kind of a feature available?

      • Workplace - Zoholics Europe Customer Awards

        Dear Zoho Mail Community! 📣 We're excited to announce that at this year's Zoholics events across Europe, we're holding customer awards for the first time ever! Workplace - Zoholics Europe Customer Awards This is your chance to shout about the amazing

      • Zoholics Europe Customer Awards

        Dear Zoho Workplace Community! 📣 We're excited to announce that at this year's Zoholics events across Europe, we're holding customer awards for the first time ever! Workplace - Zoholics Europe Customer Awards This is your chance to shout about the amazing

      • Change Default Currency in Zoho Reports

        Is it possible to default all currency fields in my Reports and Tables to my local currency without having to reformat them every time?

      • [Webinar] Deluge Learning Series - Master Conditional & Operational Logic in Zoho Deluge

        We’re excited to bring you the next session in our Deluge Learning Series—a focused one-hour webinar where you’ll level up your skills in conditional and operational logic using Deluge scripting. From writing clean if-else conditions to implementing powerful

      • UPI QR Code in Invoices

        Hi, It would be easier to make payment, if UPI Qr code is generated by Zoho Books and shown in the invoice itself.  This will promote digital payments and also makes it easier for customers to pay. It would be even helpful, if QR code contains the invoice

      • WebDAV support

        I need WebDAV support so that I can upload/download (and modify) documents from my local file system. Is anything planned in his direction?

      • Zoho Inventory Item History

        Hi Zoho Inventory Team, I 've been testing the History feature on Inventory Items in a demo system and I noticed that when I changed the value of a field to a new value, the history just says "updated by - user1", it doesn't say what what field was changed

      • Filter Images in Work Drive

        Hi, what is the best way to be able to filter files by multiple descriptions, for example, the name of a person in the photo as well as, an item in the photo and other descriptions? With labels it looks like you can only select one label at once but this

      • Flow not working when trying to Create a Merged Doc with info from a custom CRM module w/ subform

        I am having a problem creating a flow that gets its info from a webhook connected to a button in a custom module in Zoho CRM. I have made a template in Writer that follows: This is a clone of  the template in the CRM mail merge which works perfectly if i do it manually through there. My flow gets the custom module entry id through a webhook, then fetches the module entry data, and creates a merge document from that data. I know the webhook and the fetch work because if i replace the "create merge

      • Smart Scheduling via Agent Confirmation

        We’re excited to introduce a smarter and more streamlined way to manage dispatched service appointments in Zoho FSM! Feature Highlights Field agents can now approve or reject service appointments assigned to them—helping reduce unnecessary workload and

      • How to delete Inactive users?

        We want to delete inactive users from our system, but went you deactivate still the names are shown at the inactive section. How to get really rid off these names? Thanks for your response! Fabian van den Barselaar

      • Help me format my signature in zoho mail

        I need to set up my signature in zoho mail then send the format to other colegues to set it up by themselves. I have isues setting up my 5 logos one after another as I am not able to give sapce between logos. After setting up my signature with logos there

      • Can i integrate bigin with google voice?

         I make all my calling through google voice to seprate my personal line from business. I want to log my calls with customers automatically but i domt see anywhere where i can do that. Any help? Im pretty sure i wont be able to. Sad

      • Custom Field for Customer ID in Zoho Commerce's Customer Section

        Hi everyone, I’m wondering if it’s possible to add a custom field in the "Customer" section of Zoho Commerce. Specifically, I need to include a "NIF" or "Customer ID" field, as it's mandatory for invoicing in Spain. I know this can be done in Zoho Inventory,

      • Introducing Zoho CRM for Everyone: A reimagined UI, next-gen Ask Zia, timeline view, and more

        Hello Everyone, Your customers may not directly observe your processes or tools, but they can perceive the gaps, missed hand-offs, and frustration that negatively impact their experience. While it is possible to achieve a great customer experience by

      • API Self Client Authtoken conversion always returns "invalid_client".

        I am having a problem when trying to convert an Authtoken to OAuth for a Self Client script.  I have made sure that the client Id, secret, and organisation are correct, and the domain is definitely ".com"/ This is the python code I am using to create

      • My client requires me to have custom pdf file names to except payment for invoices, how can I customize this before emailing.

        Hello! I love the program so far but there are a few things that are standing in the way. I hope you guys can code them in so I can keep the program for years to come. My client requires I customize the pdf file names I send in for billing. Can you please

      • Schedule mass emails, view mass emails status and more!

        Hello everyone, Mass emails help you communicate with multiple customers in a couple of clicks. We have introduced a Mass Emails dashboard in Bigin so that users can see the status of the mass emails like how many emails were opened, clicked and bounced.

      • Multiple Selection/Select All for Approvals

        I have a suggestion from users regarding Approvals. In our environment, our Regional Managers can receive multiple requests for Approval or Rejection. They find it tedious to approve (or reject) each individual record. They would like to have a way to

      • How to report and analyze a multi-select field entries distinctly ?

        As many of CRM users I have many multi-select fields that allows me to choose more than one chose in one cell for a specific filed Like: Field A - A;BC - A;C -B;C But when reporting the field it will handle each cell as a "String" not multiple entries

      • Merge invoices

        This has come up three times in a month of me using the system. a client whom i do work for on a regular bases asked me to invoice separate jobs on a single invoice. I would then go and cancel the old invoices and make a new one. It would be great if i could just select the invoices and click merge to create a single invoice.

      • Zoho CRM Two currencies on one record

        Hello all, Our country is planning to transition to Euro from our local currency. The government is planning to mandate that all companies show their invoices, quotes, etc. in both currencies for a period of one year in order to protect from speculation.

      • How to get values from both tables in Join in COQL query in Zoho API

        In this below query I can get value either from Deal Table or from Contact table. If I wanted data from both the table it is not working. Can you please help me with this. Thanks in advance. {     "select_query": "select ,A.Deal_Name,B.First_Name,B.Last_Name,

      • 【Zoho CRM】日時のフィルター機能のアップデート

        ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中から、各タブで利用可能な日時のフィルター機能のアップデートをご紹介します。 日付項目と日時項目のフィルター及びカスタムビューに、「前へ(Previous)」「次へ(Next)」の選択肢が追加されました。 ⬛︎[前へ(Previous)]：作成日時に基づきレコードをフィルターにより抽出する場合 例1. 前へ6ヶ月：当月を除く直近6ヶ月間のレコードを抽出 例2. 前へ3年：今年を除く直近3年間のレコードを抽出

      • How can I notate on check stub when a vendors credit has been applied to an invoice payment?

        I'm looking for a way of printing vendor credit memo use on a check stub when its been applied to other invoices. To let my vendors know I'm using credit memo XYZ in the amount of $xx.xx. Currently I am having to handwrite it on the stub to show my vendor

      • Is there a Waiting Room Before The Webinar Starts?

        It appears that there is no waiting room before a webinar starts. For example, with most webinar software you can collaborate with your co-presenter, set up your presentation and check to make sure everything sounds right before you go live. Zoho Meeting/Webinar

      • Optimizing Zoho CRM Integration – Tips & Insights Needed

        I hope you're all doing great! I'm currently working on integrating Zoho CRM with our platform, which helps users get iPhone Free of cost through verified government programs. Everything's coming together nicely so far, but I'd really appreciate some

      • Forms - Workflow

        Apologies if this has been asked before. I would like to know if there is a way to setup a form where a customer completes the fields/questions on Page 1 and then it is forwarded to an internal department employee who completes the fields/questions on

      • Using the "Like" operator in Custom Formula

        HI there, Can someone please explain the way to use the "LIKE" operator in an IF statement to compare strings? I have tried the following but am not getting the results I'm after. if( "CurrentStatus" like 'Rejected*','Unsuccessful','Pipeline') Thanks Matt

      • ABA Files payment description

        Hi, is there a way to automate the payment description on the ABA file creation. When you paying many vendors having to put this in each time is very time-consuming. I couldn't see if there was a way to workflow this to automate using deluge.

      • GDPR Contd. - Handling Lawful Bases for Your Customers using Zoho CRM.

        Hello folks,   Continuing from our previous GDPR post, we bring to you the first cut of GDPR centric enhancements that are released for handling lawful bases for your customers in Zoho CRM. For your understanding we have split the entire process into three sections: Identifying Data Processing Basis Updating the Data Processing Basis in Zoho CRM  Consent Management in Zoho CRM 1. Identifying Data Processing Basis The fundamental principle to handle the personal data of your data subjects is to process

      • Upgrade the Lato font to the Lato 2 font

        While there's not a major difference, I noticed that Zoho doesn't use the upgraded Lato 2 font but it instead uses the standard one. Lato 2 enhances the look of letters and numbers when you italicize them, among little things that get tweaked. Is it possible

      • Masked Field Type with Permission-Controlled Visibility in Zoho CRM

        Dear Zoho CRM Team, Greetings, We would like to request a new feature that would enhance data security and access control within Zoho CRM, especially when handling sensitive internal information. Use Case: Our team occasionally needs to store sensitive

      • Next Page