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

      • Add Enable/Disable to Field Rules and other Rules

        Hi, Sometimes I have rules setup for fields, and until I want to enable them for use, I can set the fields to Hidden but rules still show them, today you have to delete rules and then recreate them again, would be nice to have a toggle for Enabled/Disabled

      • Syncing stuck for days

        Hello when I made an account a few days ago and synced all my notes to it, it is still syncing. My app is only 400mb so I do not know why it is taking so long. Please help

      • Workflow runs on every edit despite not ticking the field repeat this workflow whenever a parent is edited.....

        Hi, It is my understanding that this workflow should only trigger once. Why is this triggering on every edit of the field? Based on another support query - directly from Zoho, If i tick the box 'repeat this workflow whenever a parent is edited' it should

      • How do you add or update tags on Zoho CRM records via n8n? (Workarounds or best practices?)

        Hi all, I’m running into some limitations with the Zoho CRM node in n8n and was wondering how others have handled this: From what I see, the standard Zoho CRM node in n8n doesn’t allow you to add or update tags when creating or updating contacts/leads.

      • API PARAMETER FOR TICKET CLOSED TIME

        Hi, Is there a parameter for filtering tickets by closed time in zoho api, i can see closed time in the API response i get, but can't get tickets by that field while calling. Regards, Anvin Alias

      • Reply to email addresses wrong.

        I have setup my Zoho mail account using my main domain and I also have an Alias setup from a different domain. In Settings - Mail - Compose I have selected to the option "For replies, send using The same email address to which the email was sent to".

      • Meeting integration with Otter.ai

        Would love for an integration with an AI transcription service like Otter.ai to be integrated with Zoho Meeting. Thanks

      • How to close/delete a free creator account?

        I have a free zoho creator account associated with my email address that is not being used.  I want to become a user of another paid zoho creator account but I can not associate with the paid account with the same email.  I assume if I can close or delete the free account I will be able to use the paid account. I have emailed support but no response. Suggestions?

      • Zoho books and zapier causes Invalid data provided

        I have been using zoho books with zapier for over 2 years now, everything was working fine. On September 13th my zaps stopped working. Now on step create sales invoice in zoho books i get an error: Failed to create a create_invoice_v2 in Zoho Books The

      • CRM report

        Is it possible to pull a contacts report that also includes the company industry, as well as the company name? I’m having trouble combining company and contact fields – any help is appreciated. Thank you, Sam

      • Early Payment Discount customize Text

        Hi, I’m currently using Zoho Books and am trying to customize the standard “Early Payment Discount” message that appears in the PDF invoice template. I’ve reviewed the documentation here: https://www.zoho.com/books/help/invoice/early-payment-discount.html

      • Enhancements to Client script?

        Hi Zoho CRM, I've been extensively using Client Scripts to enhance our Deal form experience, particularly for real time validations and auto updating fields based on specific logic. However, I've encountered a challenge regarding permission boundaries.

      • Add views to new CRM UI navigation + Unlimited Webtabs

        Zoho CRM is so close now to being the ultimate business application with the new UI, as soon as this one feature is added. This is probably where Zoho is headed but if it's not I want to BEG for this to be incorporated. What we need is to be able to put

      • E-Mail Distribution List

        How do I create an e-mail distribution list in Zoho Mail?

      • Custom "create meeting" button with more functionality than Zoho currently has?

        I'm looking for a little help/direction in how to do this. Even just some general high level pointers on how this might be able to be done. The current Zoho Meeting Activity functionality is not ideal for my org's workflow. I'd like to try and create

      • Error Code 4: Invalid value passed for JSONString

        Okay, I want to start by saying I know I'm a terrible scripter, so sorry if this is a dumb mistake. I just can't figure it out, even with LLM help. Here's my code: // --- Input Variables --- customer_id = salesorder.get("customer_id"); so_id = salesorder.get("salesorder_id");

      • Organizing contacts/members by company

        I work for a membership organization (representing businesses) and am trying to use Zoho CRM more effectively for managing the points of contact for our members. Currently, our members are listed in our CRM by the primary point of contact's name, but

      • Unable to search in Zoho Email

        I've started using Zoho Email (free version) recently and realized that it doesn't have email search functionality. Am I missing anything here? I've gone through the Zoho tutorial which does show the search bar on the right top of the Zoho UI. But in

      • Response Time Report

        From data to decisions: A deep dive into ticketing system reports Every organization that interacts with its customers should have an established timeframe for how soon an agent is expected to send the first response and any reply to any follow-up messages.

      • Problem : Auto redirect from zoho flow to zoho creator

        Hi there, I've been waiting for zoho team to get back on this for last couple of days. Anyone else have the problem to access zoho flow? everytime I click on zoho flow it redirects me to zoho creator. I tried incognito mode but it still direct me to zoho

      • Zoho - Outlook plugin

        Does anyone know if there is a way to modify the autofill in the Zoho plugin in outlook? When we create a contact, it enters the correct email address and name, but then pulls information from our own signature line to add phone number, address, etc.

      • Zoho Books - Sales Person Information

        Hi Team, On Invoices, Quotes, etc... I can include the Sales Person, but it only shows their name and not their email or phone number. It would be great to have place on invoice templates where we can manage what sales person information should be shows

      • Offline working in Zoho Creator portal

        Zoho's help says that offline working is only available in the Creator mobile app and not in the portal app. But I can see offline options in the portal app too and it seems to work when I test it. My portal users are often in areas where there is poor

      • Fetch Records using Dynamic Criteria

        Hi,  I have a form that builds a filter based on user input.  I need to fetch the records based on dynamic criteria.  How would I accomplish this as there is no eval function? For example: desiredRecord = Form1[dynamicCriteria];

      • Url filter Report date (pivot chart)

        Hello. Is it possible to filter the data in pivot char using parameters in the url? I'm trying but I should not doing very well. Something like: https://creator.zoho.com/.../....../#Report:MyPivotChartReport?MyDate=01-Jan-2012;31-Jun-2012;MyDate_op=58 Saludos

      • Sending gmail to a particular person fails because the address gets changed to "gmaill", with a second "l" typo somewhere

        I send to bob@gmail.com (example) and get an error sending to bob@gmaill.com, only for this one person. Note the extra "l" in the email the system tried to send to, which was not in the address I entered. Can't find a typo in the contact or anywhere else

      • Emoji Support in Bigin CRM

        We request the implementation of emoji support across Bigin CRM. This feature should allow users to seamlessly use emojis in text fields, headlines, and deals. It would enhance communication, improve the visual appeal of records, and bring more personalization

      • Bigin Booking Pages enhancements

        I would like to ask for several enhancements for the brand new (and promising) Booking feature. 1. Add "Contact/Mobile" Field to Booking form We use Mobile as key (id), but unfortunately it is missing from the Booking form, only Home Phone is available.

      • Amount in words in Indian format

        Hi, I had coded the following code to convert amount in words. But in the code in the format of US like million. But i need in Lakh and Crore. So pls suggest ideas r post corrected code string Num2Words(int val) {     val_s = input.val.toString();     th = {"", "thousand", "million", "billion", "trillion"};     // uncomment this line for English Number System     // th = {"","thousand","million", "milliard","billion"};     dg = {"zero", "one", "two", "three", "four", "five", "six", "seven", "eight",

      • What are people using to send Service based emails?

        Zoho Campaigns is for marketing. Users can unsubscribe from these emails. Service based emails need to be delivered and can without the worry of Can-spam act. What are people using to send service based emails? My mailing list is derived from a database

      • Standalone LMS tool

        Will Zoho release a standalone LMS (Learning management System) than can be used by external parties (guest)?

      • Announcing Kiosk 1.1 - Customize screen titles, configure new fields & actions, use values from your Kiosk to update fields, and more.

        Hello all We are back again with more enhancements to Kiosk. So what's new? Enhancements made to the Components Add titles for your Kiosk screens and adjust its width to suit your viewing preferences. Three new fields can be added to your screen: Percentage,

      • An Overview of Dario Schiraldi Deutsche Bank Executive

        Hello Community, Dario Schiraldi is an executive at Deutsche Bank, focused on advancing the firm’s financial services and crafting its global strategic vision. With 20 years of expertise in leadership roles, he has spearheaded successful market acquisitions

      • Emailing a document to WorkDrive

        Does WorkDrive include the ability to upload a document by sending an attachment to an email address? (Books and Expenses include this functionality) If it doesn't is it under consideration? on the Road Map?

      • Allow Changing Appointment Status from "Completed" to "No Show" or Other Valid States

        Hi Zoho Bookings Team, We hope you're doing well. We would like to submit a feature request regarding appointment status management in Zoho Bookings. 🎯 Use Case Sometimes, an appointment is mistakenly marked as Completed, but later we realize that the

      • Ability to modify what displays in calendar invite?

        I am a long time calendly user and want to make the switch to bookings.  I understand that there is not currently a meets/hangouts integration, is one on the roadmap? Is there anyway I can modify the calendar invite to include the meet link?  I can add it to the emails no problem, but I would also like it to display on their calendar.  Is there some work around I can do to get it on the calendar?  Also am I able to modify the calendar event title?

      • Zoho One and Tally Integration

        Has Anyone in this forum done any implementation with Zoho CRM and Tally accounting software. If so who have you used and how easy was it?

      • Microsoft PowerPoint files Extremely slow to save

        I and others on my team have noticed that Microsoft PowerPoint documents are extremely slow to save when using WorkDrive. It always takes over 30 seconds to save a file. Word and Excel files seem to save in a typical length of time, but PowerPoint is

      • How can users unblock their blocked Zoho Mail accounts?

        After the reason for the account block (storage exceeded, spam detection etc.) has been rectified, the user can unblock the account from the UnBlock Me page. Account support@edu2review.com  Edu2Review is an education review platform, we rate the quality

      • Adding additional fields for batch information

        Hello, I am looking at adding additional information into our inventory module. we would like to be able to see up to 8 attributes that will be individual & different for each batch (i.e. batch specific information) but currently I seem to only be able

      • Next Page