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 URL : https://www.zohoapis.com/crm/bulk/v8/read

Request Method : POST

Request Body :

{     "callback": {         "url": "https://webhook.site/7b58ff0b-b61b-4fbf-953f-1bf8b180a3c4",         "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!!!

Previous Kaizen: Kaizen #188 - Building a Timer and Worklog Widget (Part 2)

Related Readings:

• Kaizen #124 - Manipulating Subform using Zoho CRM APIs
  
• Kaizen #125 Manipulating Multi-Select Lookup fields (MxN) using Zoho CRM APIs
  

• Topic Participants

• Subramanian K

  

• Andres

• 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

• bouncing emails

  My recurring invoices have bounced back

• Probable Scam / Phising attempt from email pretending to be Zoho

  I think this is a scam email right? It says "zohCworkplace.com". I'm on the Mail Free plan The link in the CTA button seems to go to a redirect. Just wanted to bring it up to the security team.

• Feature Request: Ability to set Default Custom Filters and apply them via URL/Deluge

  I've discovered a significant gap in how Zoho Creator handles Custom Filters for reports, and I'm hoping the Zoho team can address this in a future update. This limitation has been raised before and continues to be requested, but remains unresolved. The

• Email Address Search in "To" Field Search is broken, Zoho refuses to fix it

  Typing a part of the email address string other than the beginning of the string does NOT work, I kindly urge Zoho to fix this. Let's say you remember writing an email so someone called "smith" from company "corp.com", but can't remember their first name,

• Emails not being received by @hotmail.com, @outlook.com and a few others

  When I try to send emails from zoho mail to people with email addresses ending @outlook.com and @hotmail.com (and a few others), I get a 'delayed' automatic email and then a few hours later, an 'undelivered' automatic email. This has started a few months

• scroll bar for far left of screen

  I am unable to even see the scroll bar to the right of "inbox" etc on the left; it is stuck at "streams" and I can't get to inbox or anything else. It would help if it could be made a lighter color as the black or dark grey can't bee seen.

• OUt of office every friday

  Hi, I tryed to configure my out of office, because i'm not working or emailing on fridays. But when i select only friday as unavailable day, the out of office still sets for the whole week. What am I doing wrong?

• Signature line

  How do I set signature line in email

• Zoho email

  I cannot send email to mail.ru

• 【参加無料】東京 Zoho ユーザ交流会 NEXUS ー CRMで始めるマーケティング事例 / AI活用法(Zia Agents)

  ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 3月27日(金)に東京、新橋で東京 Zoho ユーザー交流会 NEXUS を開催します！ 昨年度までより、さらにパワーアップして戻ってきました！ ユーザー活用事例は、2人のユーザーさんからお話しいただきます。Zoho サービスの活用の幅を広げたい方や、他のユーザーの利用法を気軽に知りたい方など、多くの方にとって学びのあるセッションになること間違いなしです✨ また今年は、これまで以上に、AI機能にも焦点を当てて行く予定です。 初回として、Zoho社員からZoho

• Issue Exporting Data – CSRF Token Invalid Error

  Dear Zoho Team, We are experiencing an issue when exporting data from our Analytics workspace. Whenever we attempt to export data from our analytical pool, the system displays the following alert message: Alert Message: The CSRF token is invalid. It could

• Deluge Learning Series – Client functions in Deluge | January 2026

  We’re excited to kick-start the first session of the 2026 Deluge Learning Series (DLS) with Client functions in Deluge. For those who are new to DLS, here’s a quick overview of what the series is all about: The Deluge Learning Series takes place on the

• Zoho Mail 505 error I can not send email

  Hi, I’m having issues sending emails from my custom domain email address. When I send emails to Outlook addresses, I receive an “Undeliverable 505” error. However, emails send and receive correctly when I use Gmail. This is important for my business,

• Multiple MFA Methods

  With SMS-based MFA methods being discontinued, there is now no way to have mutliple MFA methods. I'd like to add my zoho account on two seperate phones using the Google Authenticator app. In the https://accounts.zoho.com/home#multiTFA/modes you can only

• Reuse Standalone Function

  I noticed that there's a missing information in documentation to reuse a standalone function and it is because the parameters require an argument. Here is my code and it is working. response = invokeurl [ url: "https://people.zoho.com/api/v3/function/sample/execute"

• Domain renewals

  Need to know how hoe to renew the domain

• MX shopify problem

  hello, i added all MX values in my shopify DNS - it shows those values on the shopify panel + your toolkit. I tried to send some email and it works, however on my gmail it says they cant verify this email. When i try to answer into my domain's email -

• Best Way to Manage Email Notifications While Running a Strategy Website

  I am currently managing a content-based website, and I use Zoho Mail for handling contact forms, user queries, and collaboration emails. One challenge I am facing is organizing incoming emails efficiently, especially when messages come from different

• What is the maximum email domains ?

  I help manage about 20 associations and I'm looking for a way to centralize them in one place. Does Zoho Mail pro or enterprise support 20-30 domains for 3-5 users each?

• Add to Workdrive filter

  I'm trying to create a filter that will upload attachments in emails and the e-mail body to a folder in workdrive. I am able to do one or the other (attachment, or e-mail content), but not both. I first tried it using the "Email (EML) + attachment" option.

• Forgot my admin Panel Id and password

  Sir, I have an account , where a domain mycityestate.in is added for Zoho email , now it is hard for me to manage email because i have forgotten the Email account and password registered with Admin Panel of Zoho. Just need email name which is registered

• MCP no longer works with Claude

  Anyone else notice Zoho MCP no longer works with Claude? I'm unable to turn this on in the claude chat. When I try to toggle it on, it just does nothing at all. I've tried in incognito, new browsers, etc. - nothing seems to work.

• Knowledgebase SEO

  We have a custom-domain mapped help center that is not restricted via login. I have some questions: a) will a robots.txt file still allow us to control indexing? b) do we have the ability to edit the sitemap? c) do category URLs get indexed by search

• Problem with CRM Connection not Refreshing Token

  I've setup a connection with Zoom in the CRM. I'm using this connection to automate some registrations, so my team doesn't have to manually create them in both the CRM and Zoom. Connection works great in my function until the token expires. It does not refresh and I have to manually revoke the connection and connect it again. I've chatted with Zoho about this and after emailing me that it couldn't be done I asked for specifics on why and they responded. "The connection is CRM is not a feature to

• New Features: Repeat Last Action, Insert Cut/Copied Rows/Columns and Hyperlink

  You might have noticed the constant updates to Zoho Sheet of late. Here are 3 more features that have been added to Zoho Sheet recently: F4 - Repeat Last Action Insert Cut/Copied Rows and Columns Insert Hyperlink Here is a screen cast demonstrating each of these features. Read further below to learn more about these new features. F4 - Repeat Last Action: You can now repeat the last action you made on your spreadsheet by using the keyboard shortcut, F4. It is quite handy and helps you get your work

• Need help getting my mail on iPhone and Tablet

  I need to access my Zoho mail via the iPhone Mail app. I have entered the login name, password and the incoming and outgoing servers, which my Mail Settings page says are imappro.zoho.com and smtppro.zoho.com. The iPhone keeps saying it cannot authenticate.

• Add an background image to an email template in CRM

  Hi all, We wants to put an background image behind all our email templates. Is there a way to import this thru html. If i put the option background image in <body style="background-image:...</body> and i look to the preview it shows our background, but

• Is there a way to show contact emails in the Account?

  I know I can see the emails I have sent and received on a Contact detail view, but I want to be able to see all the emails that have been sent and received between all an Accounts Contacts on the Account Detail view. That way when I see the Account detail

• How do I bulk archive my projects in ZOHO projects

  Hi, I want to archive 50 Projects in one go. Can you please help me out , How can I do this? Thanks kapil

• Copy contents of File Upload Field into Workdrive

  Hello, I have set up our CRM so that a Workdrive folder is automatically created for each Deal via workflow, this adds the id of the folder into a dedicated field. We also have a field on each Deal called 'Approved Layout', which is a file upload field.

• Deleting a memorized email address

  How can I delete a memorized email address? Even though the address has been deleted from Contacts, Zoho mail still auto suggests the address when typing it into the TO field. Thanks!

• ZeptoMail API

  Hello Since today, we experience issues with the ZeptoMail API. When trying to send e-mails using: https://api.zeptomail.eu/v1.1/email we receive the error: (503) Site unavailable due to a traffic surge. Please try again shortly. I kindly ask you to identify

• 553 Relaying disallowed. Invalid Domain - gzkcompany.ro

  Hi there, Can you please assist me in getting the right domain settings? I just renewed my domain subscription, after expired and i got error: 553 Relaying disallowed. Invalid Domain - gzkcompany.ro Zoho mail can receive emails, but its impossible to

• Not able to receive emails for a while

  I am not able to receive emails for a while now.

• Confirmation requested: eligibility and process to downgrade to Forever Free — tenant bigbanghawking.com

  Thank you for your reply. I am testing Zoho Mail from Brazil with the tenant bigbanghawking.com (endpoint: mail.zoho.com) and we are currently on the Premium trial that expires 21/01/2026. Before deciding whether to pay or cancel, I need written confirmation

• Zoho API v2.0 - get ALL users from ALL projects

  Hello,        I've been trying to work on an automatization project lately and I find it difficult to work with this strict structure. To be more explicit, if i would like to get all users participating in a project i would need to get all projects first.       Same thing with projects. If i want to get all projects, I would need to get all portals first.        The problem with this aproach is that it consumes a lot of time and resources.             I want to ask if there is another way of getting

• الموقع لا يقوم بالسداد

  السلام عليكم ورحمة الله وبركاته وبعد من أمس وانا احاول السداد للدومين YELLOWLIGHT ولا اتمكن من السداد اقوم بتعبئة جميع البيانات ولكن دون جدوى يطلع لى حدث خطأ ما

• New in Office Integrator: Enhanced document navigation with captions and cross references

  Hi users, We're pleased to introduce captions, table of tables and figures, and cross-references in the document editor in Zoho Office Integrator. This allows you to structure documents efficiently and simplify document navigation for your readers from

• Where Do I set 24h time format in Cliq?

  Where Do I set 24h time format? Thanks

• 🎉 ¡Seguimos trayendo novedades a Español Zoho Community! 🎉 Confirmada la agenda y ubicación para los Workshops Certificados

  Si todavía no te has hecho con tu entrada para nuestros Workshops Certificados del próximo 26 y 27 de marzo o, por el contrario, estabas esperando que confirmáramos dónde los celebraremos, ¡este post es para ti! 📍¿Dónde nos vemos?📍 Nuestros Workshops

• Next Page