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

      • Mail Data Migration

        Hello Team, I have an issue with my organization mail data migration from Google to Zoho. We used Google Workspace before now but decided to change to Zoho to enjoy your service. I have successfully created an account and 1. Complete Domain verification

      • Prompting email addresses when sending an email

        Hi, I was just wondering if it was possible to disable the prompt / suggestion of email addresses when you begin typing an email address into the TO or CC box? Some of the email addresses that are being suggested are people that no longer require the

      • This is a HTML email and your email client software does not support HTML email!

        I have a small business, recently the email notification is coming like this to me, can anyone please help me? I am not so IT savvy -----=_NextPart_b4583c76c623900f59ad5b420c6da260 Content-Type: multipart/alternative; boundary="----=_NextPart_b4583c76c623900f59ad5b420c6da260_alt"

      • How to insert a ZohoUser in a subform field?

        I am building an new external web app that uses the ZohoCRM REST API (v8) to push data to Zoho. How do I use the ZohoCRM REST API to insert ZohoUsers into a subform field? I've tried several approaches and none of them have worked - inserting the ID as

      • Unable to receive emails

        Hello - I set up an email account for my domain. I can send emails but cannot receive them. I believe the issue might be with incorrect IMAP configuration (?) - but im not sure and cant find where this is on the platform. Im using Zoho hosting for the

      • Zoho Account delete function

        Hello Zoho support team The issue is as follows: Step1: Created an account community@bisonenergy.net Step2: Deleted this account. Step3: Created the new group mail using the same mail address, but the data already exists. So I have to change the name

      • help, 554 5.1.8 blocked

        got this blockade, i don't know why?

      • Not Receiving Emails from Gmail, but Other Providers Work Fine

        Hello, I'm experiencing an issue where my Zoho Mail account does not receive any emails sent from Gmail addresses. However, I can successfully receive emails from other providers such as Hotmail and Yahoo. There are no problems with sending emails—I'm

      • Basic String Search Not Possible in CRM Deluge – Feature Request or Workaround?

        Hi all, I’m trying to solve what should be a very basic automation task in Zoho CRM Deluge: Find the first 11-digit number anywhere in a string (specifically an email subject). In almost any programming language—even 1980s BASIC!—this is a trivial loop:

      • Reencaminhamento de e-mails.

        Boa tarde, gostaria de saber se tem a possibilidade de realizar o reencaminhamento de um e-mail especifico. Ex. Eu recebo alguns e-mails de um remetente e gostaria que o meu amigo de trabalho também recebesse esse e-mail, somente deste destinatário, é

      • Knowledge base articles is now available in the Zoho Desk mobile app!

        Hello all,   As a customer service agent, every day you might have to deal with many questions and issues reported by the users. With Knowledge Base, you can reduce the issue resolution life cycle for your organization.   We are delighted to announce that we have brought in support for 'Knowledge Base articles' in the Zoho Desk iOS mobile app.  This feature is already available for Android users.   KB articles are available to iOS users in the latest version of the app (v2.4.9). You can update the

      • More than one "Other" response in a Multiple Choice (Many Answers) question type?

        Is there a way to have more than one "Other (Please Specify)" with a short response as an option to a Multiple Choice (Many Answers) question? I understand there may be other ways, but I am looking for this way specifically as it would be best for the

      • Zoho Surveys

        Dear Zoho Support Team, I hope this message finds you well. I am writing to inquire about the availability and documentation for the Zoho Survey API. Background: I am currently working on a project that requires programmatic access to survey data and

      • Help Needed: Jira to Zoho Projects Migration — Tickets Imported as Unassigned & Comments Under Admin Name

        Hi Zoho Team and Community, We recently completed a migration from Jira to Zoho Projects using the official import method outlined in this Zoho Help Article. Issue Summary: We had already added all users to Zoho Projects before the migration, using the

      • Zoho Finance Estimate to Deal Attachment

        Hi, I'm trying to fetch estimate pdf from zoho books and upload it as deal attachment without success. any tips how to achieve this?

      • Journeys - how do i branch on contact call result

        Hi all. I want to branch based on the Call result field in contacts. Any idea how I can do this? Also what is the best way to have this condition checked at each step? Thanks!

      • The 3.1 biggest problems with Kiosk right now

        I can see a lot of promise in Kiosk, but it currently has limited functionality that makes it a bit of an ugly duckling. It's great at some things, but woeful at others, meaning people must rely on multiple tools within CRM for their business processes.

      • Perform custom actions from the Ticket interface using Buttons

        Hello everyone, We have introduced an option to add Buttons to the tickets, which will facilitate direct access to other applications, websites, allows execution of custom workflows, and more. Accessibility and visibility of buttons The buttons can be

      • Inserting a video from library in microsite

        Hello, We have uploaded videos in our space library. We created a new event and want to use the videos in our main page our microsite. It's possible to selected image from the library, but no videos. Only URL are accepted, but videos in library have no

      • UUIDs

        Has anyone coded a Universal Unique Identifier (UUID) generator in Deluge?

      • Create Tasks in arbitrary Zoho Project triggered from CRM [Zoho Projects]

        Community, hello What I'm trying to do is to create a Zoho Project when a Deal is created in CRM and then to be able to add tasks to this Project also from Zoho CRM with the trigger (Blueprint/ Workflow). I succeeded in creating Project using Zoho Flow,

      • Invalid Client - Client ID passed does not exist

        Hi, Daniel here. i try to generate an authorization code by following this page Authorization Request - Web Apps - OAuth | Zoho Accounts https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.users.ALL&client_id=1000.myclientid&response_type=code&access_type=offline&redirect_uri=https://localhost:7195/account/integrations/zoho/tokencallback

      • Generate Token v2 api using c# sdk

        Hello I am trying to generate a access token using c# sdk but fails every time.is there any sample code so that i can implement that code to insertleads in crm.  my use case is i want to insert and update lead in zoho crm. when user signup in my website i insert the detail of that user in crm using API v1. but V2 api is more confusing that API v1 . so please can anyone provide me a sample code of c# sdk to generate token and insert lead in crm. Or is there any way to achieve this without using c#

      • Upsert your missing data without affecting the historic logs

        Dear Customers, We hope you're well! Migrating your data from a legacy system to Zoho CRM is a critical operation as it deals with treasured data. In an unfortunate event, if you have missed to move your historical datasets, you have had to repeat the

      • Dashboard won't save, nor allow me to do a "save as"

        For some reason, one of my dashboards won't let me make any modifications to it and save?  I get the "do you want to save before closing?' and I say yes and the dialogue box just stays there.  I try to do a "save as" right after I open that dashboard and I get the dialogue box that seems to let me name the new dashboard, but it won't let me save.  The dialogue box just stays there unless I hit cancel or no. Can you please help? Jamie

      • Copying Files Between Modules

        Hi, I'm creating a Deluge script and I've hit a roadblock. I'm trying to copy files from one module (let’s call it Module A) into another one (Module B). Here’s what I’m doing: record = zoho.crm.getRecordById("Module_A", record_id); files_toCopy = record.get("Files_From_A");

      • Problem with scheduled report sending in Zoho Analytics

        Problem with scheduled report sending in Zoho Analytics. Reports are not sent due to size. How can I increase it?

      • 【Zohocreator】ログについて

        ワークフローのDelugeスクリプトのinfo関数が出力するログはどこから見れますか？

      • US military addresses

        When we have a client with a US military address having them fill in a form is a problem Zoho forms doesnt acommodate them correctly. It doesn't make sense for me to have to create a secondary data model for military addresses. I have placed some links

      • Introduction of Robotics Process Automation in Zoho products

        It will be great if Zoho can start advancing from automation to robotics process automation. For a start, it can be started with smart document understanding. Provide OCR engines Google cloud, Microsoft Azure Computer vision OCR, Microsoft OCR, Omnipage

      • Automation#34 : Automate Email threading for Ticket notification

        Hello Everyone, It's been a while since we've presented an automation. However, our community has been buzzing with ideas, use cases, and discussions with our community experts and Ask the Experts session. So, here we are again, presenting an automation

      • Zoho Sigma and Catalyst IPs for Whitelist

        Hi there, We are developing a series of integrations between Zoho CRM and Zoho Desk with an on-premises system for a customer and they have firewall rules to access their server, so they are requesting the list of IPs addresses for our backend calls,

      • 【開催報告】大阪 ユーザー交流会 2025/6/5 Zoho サービスを活用して業務をアップデート

        皆さま、こんにちは。コミュニティチームの中野です。 6/5（木）に、大阪 ユーザー交流会 を開催しました。本投稿では、その様子をお届けします。 当日の登壇資料などもこちらに共有しますので、参加できなかった皆さまもご参照ください。 （Zoho社員セッションの登壇資料については、8月に開催する福岡 ユーザー交流会の開催報告で共有予定です。） 今年初の開催となる大阪 ユーザー交流会では、akippa株式会社 内藤さんによるZoho CRM / Forms の事例セッションのほか、 「見込み客・顧客データの管理/活用方法」をテーマに、参加者同士でZohoサービス

      • Moving forward, can we change our reports to send record ID's by default?

        With the new policy of not including record ID's in reports, is there a way to default to including them in my reports as they used to be?

      • WhatsApp integration isn't very useful at all (no workflow support)

        We have set up WhatsApp through Business Messaging. It works, but there appears to be no workflow support for messages that are sent/received! Without being able to trigger a workflow when an inbound message is received, my colleagues would have to manually

      • Zoho CRM 差し込み文書テンプレート if文

        Zoho CRM の差し込み文書のテンプレートを作成しています。 フッターにページが 2ページになる場合は、「次葉へ」と言う文字を表示したいのですが、ページ数による判断はできないのでしょうか？ 現在はサブフォームの行数で判断しているのですが、複数サブフォームを差し込んでいるので、合計何行で2ページ目になるのか把握が難しく、ページ数で判断できればうれしいなと思い、質問させていただきます。 ※行総数はワークフローでレコード保存時にカスタム関数でサブフォームの行数をカウントして数値を保存しています。

      • Record payment: Payment Mode vs. Deposit To and how to "connect" them!?

        How do we set up that when we choose:  "Payment Mode"= Cash, then "Deposit to" is automatically set to Petty Cash, and if we choose  "Payment Mode"= Check, then "Deposit to" is automatically set to Undeposited Checks, and if we choose  "Payment Mode"=

      • Allow split times for business hours feature

        It would be great to be able to set business hours multiple times during the same day. For example: Monday from 9am - 1pm, and then from 2pm - 5pm This would allow calls to be sent straight to voicemail during 1pm-2pm during lunch break.

      • Add Knowledge Base KB Articles to multiple categories

        Greetings, Love you help center system. One item that would be incredibly helpful to many of us would be able to add a single Knowledge Base KB article to multiple categories in our system. It seems it could be quite easy to use a checkbox form, instead

      • Error in formula

        Can someone PLEASE tell me what is wrong with this formula? Formula return type, I have tried string and decimal fn.Year(fn.Now())-fn.Year(${cf_purchase_date}) I keep getting the following error. Incorrect argument type passed for function Year Thanks

      • Next Page