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 Flow s’enrichit avec les subflows et les actions Webhook

        Nous sommes ravis d’annoncer deux ajouts importantsà Zoho Flow : les subflows et les webhooks sortants. Ces nouvelles fonctionnalités ont été conçues pour vous aider à créer des workflows plus facilement et à automatiser davantage de tâches répétitives.

      • How to assign canvas view for portal user

        Hi , as a portal user, I can switch to another canvas view, however, I cannot find any field to configure a default canvas view for portal user. May I ask how to set it up in CRM? And if I can view list by sheet view as a portal user?

      • Restrict Leave Application Based on Attendance Cycle (24th to 23rd)

        Hi Zoho Team, Our organization follows a custom attendance cycle from 24th of the current month to 23rd of the next month. I would like to configure the system so that: Employees should not be able to apply backdated leave for any date after the attendance

      • How do I assign a parent to an existing campaign?

        I created a campaign but now I'd like to make that existing campaign a child of another.  How can I do this?

      • Categorize Tickets Through The App

        I used to be able to categorize and assign tickets through the app without any issues. However, for the past year, whenever I try to edit a ticket, select a category, and click save, it doesn’t actually save the changes. As a result, I haven’t been able

      • Can't add picture to email template. Says I'm over the character limit.

        I tried creating an email template with a picture and it says I'm over the character limit. The picture is pretty small. What can I do?

      • Allow breakdown of per diem for meals provided

        Would it be possible to break the per diem down into what you get for each meal. The reason for this is we want to offer per diem but if a meal is provided by a customer or sales we need to remove this from the per diem bucket for that day. We break down

      • Automatically moving Leads into their corresponding buckets

        Hi, I have developed a lead pipeline and created different cadences for various lead segments. After enrolling leads into their respective cadences, each lead goes through a series of follow-ups (in my case, three emails). If a lead does not respond after

      • Tracking Email Template usage

        I'd like to be able to track how many times agents/users send an email from Templates. This is so we can track their activity in relation to Campaigns in CRM. Thanks

      • Get employee id of authenticated user via API

        Hi, For adding timetracking records an employee id is required. Is there an API Route available to get the employee ID of the current authenticated user? or something like /users/me Currently using https://people.zoho.com/people/api/forms/employee/getRecords

      • Zoho Social API for generating draft posts from a third-party app ?

        Hello everyone, I hope you are all well. I have a question regarding Zoho Social. I am developing an application that generates social media posts, and I would like to be able to incorporate a feature that allows saving these posts as drafts in Zoho Social.

      • Collect in-app feedback with richer context and granular insights

        Hello, Apptics community! From GenAI chatbots to one-tap checkouts, user experience standards keep rising—yet 96% of unhappy users never explain what went wrong; they simply leave. Introducing in-app feedback 2.0 banner In-app feedback 2.0 is here to

      • Temporary restiction

        My account says You have been temporarily restricted from publishing jobs from Zoho Recruit.Click here to request a one-time approval to publish your jobs and when I go to click it shows error. Kindly assist.

      • Help with Quote template for peer review

        We are wanting to do peer review of quotes/proposals, however the quote templates dont have product cost, profit margins, etc. It is difficult for a manager to approve a quote without ensuring nothing is going out at improper margins, etc. I have not

      • How many AR fields We can add in a form?

        I want to add at least 10-15 AR fields in a form. I just want to know is there any limit on the AR fields or do I need to pay extra money for using 10-15 AR fields. Thanks in advance.

      • Agent working hours

        Hi, I know it is possible to set company business hours but is it possible so that agents can have different ones? I.e. some agents cover later hours on specific weeks - can these be set so those agents that are "working" get notified about tickets etc. 

      • Disallow CLOSE if tags field is empty

        I want to introduce a mandatory condition that NEW tickets (not prior closed tickets) cannot enter the CLOSED state without first having an entry in the tags field. Is there a way I can do this?

      • Central de Ajuda - Restringir visualização de tickets

        Estou tentando configurar o Zoho Desk para que determinados usuários dentro de uma mesma conta consigam visualizar apenas os tickets criados por usuários específicos dessa conta — e não todos os tickets ou apenas os seus próprios. Até onde sei, existe

      • Business Hours with lunch break

        Our business hours are: mon - fri 08:30 - 13:00, 15:00 - 18:30. How can I handle the lunch break? If I use 8:30 - 18:30 it obviously breaks SLA. Thanks

      • Ask the Experts 21: Power up your support game with Zoho Desk Automation

        " In every business, there are tasks to automate, Zoho Desk helps with features that integrate Assignments to manage tickets and teams to align,Macros for quick actions and workflows to streamline Contracts and schedules to hold things tight, Plans run

      • If leads are assigned to a person before 4:00 PM and the stage is "Fresh Lead", then an email should be triggered at 4:00 PM to all assigned users. If leads are assigned after 4:00 PM and the stage is

        If leads are assigned to a person before 4:00 PM and the stage is "Fresh Lead", then an email should be triggered at 4:00 PM to all assigned users. If leads are assigned after 4:00 PM and the stage is "Fresh Lead", then the email should be triggered the

      • Multiselect lookup in subform

        It would be SO SO useful if subforms could support a multiselect look up field! Is this in the works??

      • Tasks as calendar events? What about a way to verify a meeting actually happened?

        I'm not sure how to best ask this, but i'm looking to add some guard-rails into zoho for the end-user. However for guardrails to be effective they can't really add extra steps for the end-user. i.e. every step that's added for the user, is another place

      • Attachments should sync between Zoho Finance in CRM and Zoho Books

        It would EXTREMELY helpful and practical if the attachments added to an invoice via Zoho Finance in CRM synced with the invoice updates in Zoho Books. Currently, attachments to an invoice updated in CRM DO NOT appear as attachments when viewing the same

      • Introducing a new home page view and UI enhancements for Dashboards

        Hello everyone,  In CRM, the home pages provide a quick view of the various happenings in a business with the help of dashboards. The home pages also help to organize one's and the team's day's work. There are three views in the home tab: Classic User's

      • Call result pop up on call when call ends

        I’d like to be able to create a pop up that appears after a call has finished that allows me to select the Call Result. I'm using RingCentral. I have seen from a previous, now locked, thread on Zoho Cares that this capability has been implemented, but

      • Data Template Amending

        Hi, is it possible to remove data templates once you have applied them in Workdrive? Also, once I have added a new field to a data template can I mass update multiple files who have already been allocated that template and amend just that one added

      • Zoho Flow y subformularios de Zoho CRM

        Buenas tardes, En mi empresa vamos a empezar a usar los subformularios de zoho crm pero estos los voy a tener que rellenar con zoho flow ya que va a ser el encargado de rellenar dichos campos del subformulario. El problema es que a la hora de intentar

      • Recurring Invoices

        We are looking at moving our invoices to ZOHO Billing, I have started the trial period and like that I can et up for four different companies. The one feature we need which is mentioned in the documentation is Recurring Invoices so we can send our Rent

      • Implement Meeting Polls in Zoho Bookings

        Dear Zoho Bookings Support Team, We'd like to propose a feature enhancement related to appointment scheduling within Zoho Bookings. Current Functionality: Zoho Bookings excels at streamlining individual appointment scheduling. Users can set availability

      • Zoho Projects App update: Arabic and Hebrew language support

        Hello everyone! In the latest version(v3.10) of the Zoho Projects iOS app update, we have brought in support to access the app in RTL(Right to Left) languages (Arabic and Hebrew). Note: RTL is yet to be supported on the Calendar and Gantt charts modules

      • I want to cancel @mention group in the notes in Zoho CRM

        Hi Everybody, I want to prevent people from mentioning a specific group in notes in Zoho CRM. We have one group called Team Sales, and although we've asked users not to mention groups, they still mention the group name. My workaround is to change the

      • Kaizen #193: Creating different fields in Zoho CRM through API

        🎊 Nearing 200th Kaizen Post – We want to hear from you! 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.

      • How to install node packages in Zoho Creator cloud functions

        I wanted to create some functions which requires node packages like axios, fetch, multer etc., How and where can i install the node packages in Zoho creator to use it in Zoho creator Nodejs function.

      • Session "Ask Me Anything" Zoho France - Le 26 Juin 2025 14h à 17h (en Français

        Chers Utilisateurs, Vous cherchez à mieux comprendre Zoho CRM ou Zoho Desk ? Nos experts seront disponibles pour répondre à toutes vos questions lors de notre session Ask Me Anything. Rejoignez-nous ici pour en discuter en ligne. Pendant trois heures,

      • Option to Crop Existing Agent Image in Zoho One Directory

        Hello Zoho Team, We hope you're all doing well. We would like to request a small but useful enhancement to the Zoho One Directory. 🎯 Current Limitation At present, the system allows cropping an agent image only during the initial upload of an agent's

      • Introducing Sub-Accounts in Zoho Books!

        Hello Everyone, Sub-Accounts is LIVE! Yes, you read it right. The much needed and most requested feature is now live in Zoho Books. The sub-accounts feature in Zoho Books will help you to classify your accounts further which will give you a more detailed view of your accounts while running reports. You can create sub-accounts for the below Accounts: Asset Cost of Goods Sold Expense Liability Fixed Asset Other Asset Other Current Asset Long Term Liability Other Current Liability Other Liability Other

      • Sesión "Ask me anything" Zoho en Español - 26 de junio de 2025, de 14:00 a 17:00 (en español)

        ¡Hola Comunidad! ¿Quieres entender mejor Zoho CRM o Zoho Desk? Nuestros expertos estarán disponibles para responder a todas tus preguntas durante nuestra sesión "Ask me anything". Puedes comentar este artículo y durante tres horas, nuestro equipo estará

      • UI Update: We've Reorganized Invoice Settings

        Dear users, We’ve reorganized invoice settings to offer you a streamlined and intuitive experience when managing your subscriptions. Starting from 2 July 2025, subscription-related invoice settings will be accessible from a new page called Billing Preferences

      • Marketer’s Space – Automate Subscription Management for CRM Contacts Using Workflows in Zoho Campaigns

        Hello, marketers! Welcome back to Marketer’s Space. In this week’s post, we’ll look at how to simplify subscription management using Workflows for contacts synced from Zoho CRM in Zoho Campaigns. There are multiple ways to assign topics to your contacts:

      • Next Page