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

      • Compensation Cess on Coal ₹400 per tonne. ?????

        The compensation cess rate varies by the type of product. And the cess is calculated based on the value of the product without GST. Coal, for example, comes with a cess of ₹400 per tonne. That means that if you sell 2 tonnes of coal that have a value

      • 7 month over zoho book purchase but still not immpliments Golive

        7 month over zoho book purchase but still not immpliments Golive one problems zoho team short out then other problems come still very poor mangments and immliments team . struggling with the templates in ZOHO Books. Especially with the placement of some

      • SMS to customers from within Bigin

        Hi All, Is there anyone else crying out for Bigin SMS capability to send an SMS to customers directly from the Bigin interface? We have inbuilt telephony already with call recordings which works well. What's lacking is the ability to send and receive

      • Parent & Member Accounts (batch updating / inheritance)

        Hello, I find the Parent Account functionality very useful for creating custom views and reports, but was wondering if I can also carry out batch editing on all members (aka children) of a Parent Account at the same time. Alternatively, can I set members to automatically inherit the values of the parent? For example: We have a chain of supermarkets that buy our products. These supermarkets are all members of a Parent Account in our CRM. We release a new product and all of the member stores wish to

      • Edit Legend of Chart

        I would like to edit the legend of the chart. Every time I enable the legend, I get a very unhelpful (1), and when I try to type to change to what I would desire, nothing happens, which is very frustrating. I've gone through your online tutorials and nowhere can I find a legend settings button. This seems a simple fix, where can edit the legend? Thanks.

      • Extended timeouts for APIs beyond 40secs for to accomodate LLMs

        A 40 second max response time for API calls is fine when connecting to most services, however is unsuitable when dealing with LLMs (ChatGPT/Claude/Gemini) where the response timing is very uncertain. Is there any way to increase this? It would be great

      • Deletion of Zoho Account

        To whom it may concern, Good day, My account has been created incorrectly in Zoho and I am not able to join my Company's Zoho account - attached screenshot for your kind reference Alphatronmarine - Portal Kindly advise procedure to delete this current

      • Workflow for deposit to bank account

        Hello, Is it possible to make a workflow when a deposit is made to your bank account which is coupled to Zoho books? I want Zoho to sent an email each time a deposit is made to our bank account via a workflow. Regards, Steven

      • Marking Retainer invoice paid through Deluge

        Hey Everyone, We have a scenario where we are collecting deposit payments on our website. Now, in zoho books, we need to create a retainer invoice and mark it as paid automatically using deluge just like we can mark normal invoices as paid. I have tried

      • Create a new record in custom module vi custom button

        I have zoho books premium plan . I have 2 custom modules in zoho books. 1. Goods Receipt 2. Delivery Order, I need to select multiple records from Goods Receipt and create a new Delivery order from these multiple records. (like multilple sales order into

      • Profile date settings

        At present I have "EEE, MMMM dd, yyyy" but this takes an exessive amount of column space, we should be able to input our own format. I would like to use "EEE, MMM dd, yy" - a much shorter version of the above but with the same abbreviated info, requiring

      • Delivery Method Field in Sales Order Module

        In Books and in Sales orders, the "Delivery Method" field seems to allow for anything to be entered and it seems to store those entries for future use.  When you chose to convert a sales order to a purchase order, the related field is now called "Shipment

      • Editing / Removing stages for pipeline

        Hello, I'm trying to create a new pipeline. I created a new stage and made an error when entering the probability. How can I edit fields in stages that I created? Can I delete these stages from "Add Stages" list?

      • Dynamically Filter User Lookup in CRM Subform

        We have a subform called Pricing Calculator in the Zoho CRM Opportunity module and need some assistance. Current Setup: First column: Picklist (Level) Second column: User Lookup field When a Level is selected, we want the User lookup to display only users

      • change time zone

        can't seem to figure out how to change the time zone of the project

      • Bigin iOS app update: Built-in telephony and RingCentral support

        Hello everyone! We are excited to introduce Built-In Telephony and RingCentral support in the latest iOS version(v1.11.13) of the Bigin mobile app. Once the integration is completed on the Bigin desktop site(bigin.zoho.com), you can choose the Built-In

      • Add Image or Update Image API - for Items Module

        I am trying to add new Items to Zoho Inventory from Zoho Creator. I achieved this using Zoho Inventory Create Item API, but how to add or update the item image from Zoho Creator to Zoho Inventory Item Module?

      • Introducing Booking Pages—a topping for your Calendar Scheduling needs!

        Greetings, We're here with a new topping for Bigin! Let's dive into the details. What does this topping do? Scheduling appointments with customers is one of the most common challenges small businesses face on a daily basis, as it often involves frequent

      • Debugging `try` blocks : Tip

        I find it annoying that if one line inside a `try` block has an error, the Deluge arser points the beginning of the block to the location of the error. BUT, if you temporarily comment out the initial `try {`  The parser goes through the whole block and

      • Use approval workflow comments in record scripts

        Greetings, i'm running an approval workflow for my records, during approval/rejection there is a step where comments are entered. i want to add there comments to the record and to use them in various deluge scripts like sending emails and so on.  how

      • ZOHO Store

        Not able to make a payment We are using Zoho One, and we are from India. The payment currency, which shows for us, is in USD. But the system says we can choose Country/Region India if it shows INR only. Attaching screenshots for more info.

      • Support Migration into Aliases in Zoho Mail

        Hello Zoho Mail Team, How are you? We are in the process of migrating some of our users from Google Workspace (Gmail and Google Drive) to Zoho. During this process, we noticed that Zoho Mail currently only supports migration into a primary mailbox and

      • API for Z Workdrive Flow Make-Integromat ?

        We are zoho workdrive fans Also we would like to have an api to work with Zoho Flow or with Make better known by its old name INTEGROMAT Is it planned and when? 3 months -6 months or more?

      • Apps Pane no longer visible

        I have read all the info and help and nothing works, I do not have a "show apps" anywhere and I can no longer see my Apps pane in the left hand side of mail, please advise how to get this back

      • 5名限定 課題解決型ワークショップイベント Zoho ワークアウト開催のお知らせ(8/21)

        ユーザーの皆さま、こんにちは。Zoho ユーザーコミュニティチームの藤澤です。 8月開催のZoho ワークアウトについてお知らせします。 今回はZoomにてオンライン開催します。 ▷▷参加登録はこちら：https://us02web.zoom.us/meeting/register/eVOEnBsSQ2uvX4WN5Z5DeQ ━━━━━━━━━━━━━━━━━━━━━━━━ Zoho ワークアウトとは？ Zoho ユーザー同士で交流しながら、サービスに関する疑問や不明点の解消を目的とした「Zoho

      • New in Zoho Forms: Inline OTP Verification

        Hello form builders, We are excited to announce the launch of Inline OTP Verification in Zoho Forms, a smarter way to ensure the authenticity of the contact details you collect. Until now, OTP Verification in Zoho Forms worked as a pre-access step: respondents

      • Zoho Mail : Associate emails with Meeting records and allow multiple emails to be assocaited at once

        Is there a workaround that would allow either of these? I want to associate emails with Meeting records. I also would like to be able to select multiple emails at once for association with a record.

      • Create task from email

        Is there a way on mobile to create a task from an email? I use this feature a lot and when traveling now I read email on mobile. By the time I get to my office I forget about them since I didn't add it to a task. Is this feature missing on moble?

      • Zoho Socials - Unable to view Channels and SmartQ

        Hi, The channel Facebook has been added by the admin, however, it is not visible on the User level (employee). Other channels are visible. Also, we have the premium account, and SmartQ is not working. Can anyone help? Regards, Priyanka

      • Eliminating Manual Consolidation: Automating Currency Field Sync from Task to Project

        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:

      • We want to set the "Converted from Lead" value in Deals using a Workflow or via a Deluge script. How?

        For use in Zoho Analytics, we need the field "Converted from Lead" filled in our deal records. This field is empty everywhere, because we do not create deals directly when converting a lead to a contact. We want to do that using the API or a workflow

      • Sales Orders: Quoted_Items + items in another subform -> into Ordered_Items ?

        hello, When creating Sales Orders, is it posible to inherit/fill the Ordered_Items with all the items from Quoted_Items + all the items from a customized subform with similar fields? Since you can create a sales order in different ways (convert, new -

      • How to cancel the GSTR1 pushed to GSTN

        How to cancel the GSTR1 Pushed to GSTN, some rectifications to be done in HSN & SAC code

      • Zoho Books API — Invalid Operation Type / Scope does not exist

        Hello Team, We are unable to use the Zoho Books API from our registered application. We’ve already: Created a client in Zoho API Console using (Admin in Books) Generated the OAuth code and token successfully Used the correct scopes: ZohoBooks.fullaccess,ZohoOauth.userinfo.READ

      • Enhancements in Canvas

        Dear All, Greetings! Canvas lets you design the record details page to suit your brand or business preferences. We are glad to introduce the following enhancements to uplift your design experience. Reusable Components Style Presets Let's go! Reusable

      • Minimum order quantity

        Is there a way to enforce a minimum order quantity - ie has to have a minimum of 250?

      • 【Zoho CRM】ポータル機能のアップデート：UIとポータルの作成フローの変更

        ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中から、ポータル機能のアップデートをご紹介します。 目次 概要 ユーザーグループの作成フローの変更 ユーザーグループ詳細画面内のタブについて 「タブと権限」タブについて 「設定」タブについて 概要 UIとポータルの作成フローが変更されました。ポータルの新機能に先立ち、UIを一部変更しました。タブやオプションの配置を見直し、機能へよりアクセスしやすくなっています。 また、「ポータルユーザーの種類」は今後、「ユーザーグループ」と呼称され、ページ上のボタンも「ユーザーグループを作成する」に変更されます。

      • Tax on Imported goods charged by Shipping Company

        Hi Folks, I imported goods from outside Canada, for better understanding I will give an example data. imported goods value: 2000$ The shipping company sent me an invoice containing the following information: Custom duty on imported goods: 400$ Administration

      • Zoho Webinar via Social Media

        Hello, is it possible to stream a Zoho Webinar via Social Media like Linkedin or Facebook?

      • Add Hebrew & RTL Support to Feedback Widget

        Hello Zoho Desk Team, How are you? We are using Zoho Desk and would like to utilize the Feedback Widget. While Zoho Desk itself supports Hebrew and RTL, the Feedback Widget unfortunately does not. We kindly request that Hebrew and full RTL support be

      • Next Page