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

      • Zoho Projects Android app update: Enhanced Documents module within the projects.

        Hello everyone! In the latest Android version(v3.9.35) of the Zoho Projects app update, we have enhanced the documents module within the projects. Now, you can view all the attachments that you have added across the project in tasks, bugs, comments, etc,

      • Lead Source Disappears

        When adding a new lead and saving the page, the page refreshes itself and the lead source field becomes blank. We set the "Lead source" as a required field to see if it would help, but the problem persists and we always have to re-enter the lead sou

      • Inquiry Regarding Monitoring ZOHO CRM API Credit Usage

        Hello ZOHO Community, I hope this message finds you well. I have a question regarding monitoring the usage and remaining credits of the ZOHO CRM API. I recently discovered that within ZOHO CRM, by navigating to Settings ⇒ Developer Hub ⇒ APIs & SDKs,

      • Payment Gateways - A unified hub to manage all your payment integrations in Zoho Creator

        Hello everyone, We're thrilled to announce that we've completely reimagined the way payment gateways are handled in Creator. The result is a centralized Payment Gateways section that provides a clean, user-friendly interface to configure and manage all

      • Community Digest Julio 2025 - Todas las novedades en Español Zoho Community

        ¡Hola, Español Zoho Community! Ha pasado un tiempo desde el último Digest pero, ¡ya estamos de vuelta con las novedades más relevantes en las aplicaciones de Zoho y su universo! Si no te quieres perder ninguna de las novedades que vamos publicando, te

      • Tip #35- How to use Notifications in Zoho Assist to stay on top of session activities- 'Insider Insights'

        Hello Zoho Assist Community! This week, we’re exploring Zoho Assist’s built-in notification system for improved visibility and accountability. Keeping track of session activity is crucial, especially when you're managing multiple remote devices and technicians.

      • Assistance with Exporting Specific Data from Zoho CRM

        Hi, Could you please guide me on how to export specific information, such as the model number and serial number, from the Accounts module in Zoho CRM? Thank you in advance for your assistance.

      • Coming Soon in Zoho Invoice: Send Invoices Instantly via WhatsApp

        We're working on bringing a new level of convenience to your invoicing experience. Introducing a much-requested feature in Zoho Invoice: You can now share invoices directly to your customers via WhatsApp! With this new option, you can: Share invoices

      • field update from the value of another field

        Hello, I need to do a field update from the value of another field, but i don´t know how can i do it. In the mass update option it is not possible... I need to put the last name value form the leads module to other custom field that i have created. thanks for your help

      • What is a realistic turnaround time for account review for ZeptoMail?

        On signing up it said 2-3 business days. I am on business-day 6 and have had zero contact of any kind. No follow-up questions, no approval or decline. Attempts to "leave a message" or use the "Contact Us" form have just vanished without a trace. It still

      • Is there any way to prevent the row cloning feature(on edit page)

        My initial requirement is to prevent some users from adding new rows in the subform. For that, I have implemented the client script, and the script is working fine. But users are able to clone the row and make changes. For that, I was unable to find any

      • Using Another Field Value for Workflow Field Update

        I'm trying to setup a Workflow with a "Field Update" action on the Lead module, but I would like the new value to actually be taken from a DIFFERENT Field's on the Lead record (vs just defining some static value..) Is this possible? Could I simply use

      • How Do I Change Business Location

        Ive just shifted my business to a new country and would like to update my address and Business location in the "Organisation Profile" page but it is locked in the previous country. How do I unlock it / change it? Thanks

      • Verify details pop-up windows

        Hi, Is it possible to turn-off the anoying "Verify details" window that ask for closing date, "Reason for Lost" or other concepts. If I would like the user to enter such data, I will implement a rule .... How can I turn-off such pop-up? it's not necessary

      • Monthly overtime wrong after adding/changing attendance time for past month

        Hi there, as I understand it, the montly overtime overview under attendance is calculated at the end of each month. If someone was not able to enter his attendance in time but entered it in the new month, this time will not be considered in the overview.

      • As a security measure, you need to link your phone number with this account and verify it to proceed further.

        I want to disable this feature as my one staff travels with different phone numbers so it is hard to verify by phone. How do I do that?

      • Asset Tracking

        I am looking to create custom modules to track customer assets. We install serialized and non-serialized equipment into customers vehicles. So we will have vehicles belonging to the customer then equipment that will belong to a vehicle (if installed)

      • 【参加無料】8月8日(金) 福岡 ユーザ交流会 参加登録 受付開始！

        ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 8月8日(金)に1年ぶりに、福岡でZoho ユーザー交流会を開催します！ ユーザー事例セッションでは、CreativeStudio樂合同会社の前田 美知太郎さまが、労働時間を削減したZoho活用のリアルな工夫を語ります。 Zoho社員セッションでは、データ収集から自動処理まで一気に効率化できるZoho Formsの最新活用アイディアをお届けします。 ▷▷詳細はこちら：https://www.zohomeetups.com/Fukuoka2025#/?affl=fuk2508forumpost

      • Unusable due to "server" issues but there's nothing on Zoho or Down Detector saying there's an outage

        I just started the Zoho trial and I cannot do anything because no apps or even the "contact support" will actually load. I tried to create a project but it keeps giving me the error "server is unable to process your request at this time". I tried to load

      • Issue After Updating to Zoho Desk Android SDK v4.5.0 – Authentication Fails (Status Code 204)

        Hi Zoho Support Team, I was previously using the Zoho Desk Android SDK with the following dependency: implementation 'com.zoho.desk:asapsdk:3.0_BETA_17' Everything was working as expected — including user authentication, the tickets section, and the

      • add another department to helpcenter

        After activating multi-brand, how to add another department to help center? For example department A has associated with help center 1. We have another department B and would like user to be able to submit ticket to department B via help center 1, how

      • Task and Milestones - Dependency feature needed

        I'm sure we're not the first to bring this up. We've been using zoho project for a while. Every project manager knows that to manage a successful project you need option to stack tasks and milestones and be able to create dependencies between tasks and milestones. I think you get the idea... Can you let us know if this feature is in the making or not? any chance we'll see this in future releases? If you need customer feedback about this feature or other enhancements, we'll be happy to test new products

      • How to update task start date when project start date changes?

        Hi there, When the start date of a project changes, it's important to update the start dates of the tasks associated with that project to reflect the new timeline. Is there a way to shift the start date of all project tasks when the start date of a project

      • ZOHO DESK | SET PERMISSION NOT TO ALLOW SPECIFIC AGENTS TO CREATE TICKET

        Hi Zoho Team, I have a question regarding this: "Team Desk are the ones to have the permission to create a ticket, Team OPS resolvers must not create a ticket." - How to set permission to Team OPS resolvers for not creating a ticket? Only Team Desk should

      • On success Workflow not triggering from external Zoho Form submission

        Hello everyone, I'd really appreciate your help. I'm building a system, where I'm using Zoho Creator as a crm/spreadsheet to manage movements of inventory. I have 3 "forms" or tables, where one is a main table for obersving status on all inventory, another

      • Tax is missing in expense unable to submit report

        Im getting the above error when submitting a report with an expense. Its complaining about the Tax is missing but there is no Tax area just "Amount". And if I try to Itemize the amount to break out the tax portions with the initial product portion it

      • Time-based Automations updates does not trigger Webhook

        Hi, When a ticket is updated by Time-based automation, it doesn't seem to trigger the webhook event. I looked at the ticket history for the problematic tickets, they were all changes made by action with this label: `Ticket was updated through a Time-based

      • Can't find parent child ticketing

        Hi I can't find parent child ticketing under tickets in this new organization... I have in the past on other organizations

      • Filtering Parent and Child Tickets in Analytics

        Hello Zoho Support Team, We’ve noticed that when checking our ticket analytics in Zoho Desk, the data merges both parent and child tickets for key metrics like the number of new tickets, closed tickets, and first response time. This results in inaccurate

      • Link Zoho Inventory Sales Order with Zoho Desk Ticket

        I'd like to, in a Zoho Inventory Sales Order, see linked/related Zoho Desk tickets. When I'm in Zoho Desk, I can look up related tickets to the sales order, but I can't seem to do it in the reverse manner (where when I'm in a Zoho Inventroy Sales Order,

      • Shopify integration

        I need to integrate Shopify with Zoho Books

      • Can't type latin characters Mac x Windows

        I access a Win XP machine using Chrome on Mac OS X High Sierra and I can't get special characters like á é ó â ê ô ã õ à í ú to work. I tried a few different keyboard layout setups, but nothing worked. I end up having to type a lot of stuff in a local notepad for further copy and paste, which is not convenient at all. Am I missing anything? How can I make this work? Thanks.

      • Zoho People & Zoho CRM Calendar

        Hi, Does anyone know if it is possible to link Zoho People and the calendar in CRM? I would like when holidays are approved they automatically appear in the calendar on CRM. Thanks 

      • How to add Leave Type Permission Start Time

        Hi, I have a requirement to add Leave Type : Permission Start Time on the email template to which is end to the reporting manager. But I am unable to find the field in the list of fields. How to achieve this?

      • How to get batch number of item by api?

        Hi there, Is there any way to get batch number of item by api? Batch number is the batch reference number in https://www.zoho.com/inventory/help/advanced-inventory-tracking/batch-tracking.html . When I call the https://www.zoho.com/books/api/v3/#Items_Get_an_item

      • Questions about ACH in Zoho Billing

        We have ACH enabled for subscriptions in Zoho Billing and we have the option enabled for users to be able to log in to their bank to add the account to their payment methods. Questions: 1) If the user's bank isn't supported via the log-in method, will

      • Zoho Writer Default Publish Setting for Mail Merge

        Hello, I was thinking of using Mail Merge to create documents from CRM and automatically link them. However, I noticed the "publish" function and it seems the default is "to the world". This creates some anxiety as it is not clear what this "to the world"

      • Contacts Profile

        Is there a way to add a picture to my contacts profile? You have an outline of a person but no way I can see to import a picture.

      • Tip 46: View resource allocation while adding or editing tasks

        Keeping track of employees workload can be daunting but also necessary. Overloading employees with work can cause burnout and reduce productivity.  Managers should be able to identify resources who are less engaged when assigning tasks. This will ensure a balanced workload and also improve employee's efficiency. Zoho Projects lets you identify resources who are available to take up a job when you add or edit a task.  ​ Assign the task to team members and the calendar in the Start Date field will display

      • Switching Between Multiple Zoho One Organizations in New UI

        Here’s a polished version in English that you can use on Zoho’s support or community forum: Subject: Switching Between Multiple Zoho One Organizations in New UI Hello Zoho Community / Support Team, I’m currently managing two independent Zoho One organizations.

      • Next Page