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

      • Global Fields

        Just like Global Sets for Picklists, we would like to have global fields for any kind of field. Three things that should be saved globally: 1. The Existence of the field 2. The Name and 3. Association with a module should be set up in a respective place

      • Introducing Screen Share with Audio

        Share your entire screen or just the chrome tab with audio for more engaging presentations. Your audience will hear sound just like you do, whether it's a video, demo or any other content. This is ideal for training sessions, team meetings, and client

      • Need Help Preventing Overselling in Zoho Inventory

        Hi fellow Zoho Inventory users, I'm reaching out for advice on managing inventory control in our growing business. We've recently encountered situations where sales orders get confirmed despite insufficient stock, creating operational challenges. Our

      • Tip #53: Populate and search values from tables using Table Lookup

        Qntrl supports tables to store organization-related data and access it easily. Data stored here can be populated and displayed in orchestration using Table Lookups. This helps organizations list sizeable data in dropdown or multiselect dropdown fields

      • Introducing more AES digital signature options in Zoho Sign

        Greetings! Zoho Sign has continually strived to partner with trust service providers across the globe to give you complete security and confidence, so you can e-sign documents no matter where you are. We've recently partnered with IgniSign, a trust service

      • Shuffling between one note to the next

        I usually start all my notes per interaction with a contact with the date and then a little detail. But when I search for it it only see a small portion of the note and can't immediately tell which contact its associated with. can we make the note content

      • Important Update: TRAI Mandates New SMS Header Format

        Hello everyone, We have an announcement regarding a new regulation by the Telephone Regulatory Authority of India (TRAI) that affects all application-to-person (A2P) SMS services. Starting on May 6, 2025, TRAI has mandated that telecom service providers

      • Preview generation in progress for days

        I uploaded a video file to Zoho webinar. The file has been showing Preview generation in progress for days. Pls help, why is not approved?

      • Workdrive Upload Notification

        Is there a way to be notified when someone externally has uploaded files to a folder? The "Unread" tab is really worthless because it shows all files from every directory on the system. I just need an email (or bell at worst) that says "someone has uploaded into <foldername>".

      • Workflow for "Expenses" module?

        Hi there, over the last 2 years, Zoho Expense has seen tremendous growth and we are happy with it. But, sometimes it is frustrating to see things are being implemented halfheartedly, or so it seems. For example, There is the possibility to create workflows

      • Markup instead of discount??

        Is it possible to have the discount field on an invoice or estimate be a markup instead? It's the very same functionality that I am looking for - to be able to markup an individual item by either a $ or a % and have that cost added (instead of subtracted) to the item cost.  Currently, I use the tax feature to accomplish this, but it's very awkward to have "Markup 15%" listed after the subtotal. Plus, if I want to markup items at different rates, I end up with several "markup" lines in the totals

      • Allow Mapping of Zoho Desk Knowledge Base Categories to Multiple Departments in Zoho SalesIQ

        Hello Zoho Team, We hope you're doing well. We would like to request an enhancement to the Zoho SalesIQ integration with Zoho Desk, specifically regarding the way Knowledge Base (KB) articles are mapped and displayed across departments. Current Limitation

      • Announcing new features in Trident for Windows (v.1.27.4.0)

        Hello Community, Trident for Windows is here with exciting new features to elevate your communication and enhance productivity. Let’s dive into what’s new! Smart Sign-in. You can now sign in to Trident with Smart Sign-in. With this new addition, you can

      • Add Lookup Field in Tasks Module

        Hello, I have a need to add a Lookup field in addition to the ones that are already there in the Tasks module. I've seen this thread and so understand that the reason lookup fields may not be part of it is that there are already links to the tables (

      • Time Entry : Auto fill fields Hours minutes seconds

        Hello world, Do someone know a script (for workflow rules) which fill automatically fields hours spent, minutes spent, seconds spent when we fill Executed time and End time Formula should start from (End time - Executed time) Thx in advance

      • Zoho Forms - edit the settings of the Zoho CRM field to change the integration with CRM

        I've created a Zoho CRM field in my form to pre-populate selected CRM details into the form, following the instructions here https://help.zoho.com/portal/en/kb/crm/integrations/zoho/zoho-forms/articles/zoho-forms-crm-integration#Step_2_-_Add_Zoho_CRM_Field_in_the_form

      • Ability to add notes to an appointment and add notes/attach docs to a consultation

        As an idea for the future, it would be helpful to be able to add notes to an existing appointment--there is a place to add notes for the customer, but I don't see one for the appointment. It would also be helpful to be able to add notes or attach documents

      • Im trying to white list domain dynamically in zoho desk extension

        Im trying to white list domain dynamically in zoho desk extension. But it show error Error: {errMsg: 'No entry found in plugin-manifest whiteListedDomains for requested URL'} syntax "config": [ { "displayName":"Shopify Admin API access token ", "name":

      • Zoho Payroll: Product Updates for India - May 2025

        This May, we are glad to unveil new capabilities in Zoho Payroll that simplify your payroll activities. Here's the list: Let Employees Choose Their Tax Deduction Method for One-Time Payments Calculate variable earnings based on percentage of CTC Carry

      • Bulk Update Tasks/Task Lists/Milestones

        Is there a way to bulk update tasks/task lists/milestones? We have several projects that are in the same template, and our staff complete them tasks at a time - and would like to go in an bulk update all related tasks/task lists/milestones at once. But you can't do this. I remember in an old version you could export your tasks, update the excel doc and reimport. But it doesn't seem like that option is available anymore. Can someone provide a solution/idea? Otherwise we are spending a lot of time

      • Sync failed: Invalid Date value

        Hi, I have a local .sqlite database. After importing one table through the Databridge, and produced my dashboards, I cannot sync. I get an error regarding the date column: [Line: 2 Field: 4] (2018-07-12) -ERROR: Invalid Date value The data found at the

      • Office 365 is marking us as "bulk"

        All of a sudden (like a couple of days ago) all of our customers who are on Office 365 are getting our mails in their junk email. This is not the case with Gmail or other random mail servers, nor between us. We got a 10/10 score on mail-tester.com. Also,

      • Zoho Assist

        Hi, We are using zoho assist unattended access in some windows server 2012 and recently the agent lets you connect but not let you do anything on the remote machine. Sometimes you can click on something but nothing happens. There's a issue with this new

      • Modify workflow from "ON CREATE & EDIT" to "ON CREATE" only

        Salut, Is there a way to easilly change my choice of trigger of workflow from on create & edit to on create only, or do I have to re-do the whole worklow from scratch ? Sylvain

      • Access custom modules via API?

        Is it possible to access a custom module in Zoho Inventory via the API? I can not find any reference to this in the API docs.

      • Welcome to the Zoho Service Plus community

        Hey everyone, We are excited to welcome you to be a part of the Zoho Service Plus community. Here's a quick overview of what Service Plus is all about and how the community can help us work together. What's Zoho Service Plus? Zoho Service Plus is a unified

      • Restrict Zoho Cliq Webinars and Announcements to Admins Only

        Hi Zoho Team, We hope you're doing well. We would like to raise a feature request regarding in-app announcements in Zoho Cliq, such as the recent webinar popup about the Cliq Developer Platform: While these announcements are useful, they are not always

      • Share Notebook with group created in Zoho One

        I have created a group in Zoho One for a section in my company. Is it possible to share a notebook with that Zoho One Group? Currently, it seems only possible to share to emails. Unfortunately for large teams, this will mean we are constantly having to

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

        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,

      • Outlook Add-in security times out needs to login 10 times a day

        hi we've just switched the Zoho. We use Azure SSO. All users have stopped using it. Sometimes it asks every 5 minutes. What should I lot at to solve this?

      • Simplify Zoho API integration with Deluge’s invokeAPI task

        Hello all! Happy New Year! As we kick off 2025, we’re excited to share some of the latest updates to enhance your Deluge experience. While Deluge already offered robust API integration capabilities, we’ve taken it to the next level with the introduction

      • Simplify Zoho API integration with Deluge’s invokeAPI task

        Hello all! Happy New Year! As we kick off 2025, we’re excited to share some of the latest updates to enhance your Deluge experience. While Deluge already offered robust API integration capabilities, we’ve taken it to the next level with the introduction

      • Attention: Display Issues on Chromium Browsers with Intel® Core™ Ultra Processors

        Dear Customers, We've recently identified a display-related issue that may affect some of our Zoho Assist users, particularly technicians using devices powered by Intel® Core™ Ultra Processors. What’s Happening? If you're running a Chromium-based browser

      • Is the "schedule 10 mass emails/module" limit a per user or per organization limit?

        For scheduling emails out of Zoho CRM, there is a 10 scheduled mass emails per module limit according to Zoho documentation (https://help.zoho.com/portal/en/kb/crm/faqs/emails/articles/how-to-schedule-mass-emails-in-zoho-crm). Is this limit per user or

      • How do I show file uploads in my Zoho Creator approval workflow?

        As far as I can tell I'm not able to add the file upload field to the approval workflow show fields list. As a work around I'm making a plain text field that links to the files URL. But I'm not sure how to get a link to that url that will me to preview

      • Zoho Bookings - variable appointments

        Hello, I am looking to see if its possible for zoho bookings to recognise booking slots in the calendar or a way to do this. I would like appointments only booked in at certain times of the day and this could vary per host. I have provided a calendar

      • Best Practices - Extensions for Zoho Finance Suite

        With Sigma, the extension developer platform, you can create custom extensions that enhance the functionality of Zoho Finance apps like Zoho Books, Zoho Billing, Zoho Inventory, Zoho Expense, and Zoho Invoice. Here’s how to get started: Sign up: Create

      • QR code image is not exported in PDFs

        The new QR code field works fine when I include it in a report template and I choose the print option: https://creatorapp.zoho.com/<username>/<app_link_name>/record-print/<report_link_name>/<record_ID>/ But when I try to save the document to a .pdf file

      • Zoho Form to Zoho Form Integration

        I've created an application form that asks for references. I would like the submission of the application form to trigger a form to the reference using the email id and name entered in the first form. In the reference form that is triggered I need to

      • CRM: related table using module queries, are links possible?

        Hello. I was exploring the possibility of using a module query to get a filtered related list. For example, I'm using a Canvas custom details page and if an account has an open deal I'd like it to appear at the very beginning of the account page, with

      • Next Page