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

      • Making money out of Zoho Sheets - How?

        Hello, Suppose I come up with a brilliant Zoho Sheet that I want to sell to other people, can I do this? How? Thanks.

      • Mobile Display Issues on Zoho Sites After Recent Update

        Hello! I’m currently facing an issue with my Zoho website that I created for my small business. After the recent updates, I’ve noticed that my site is not displaying correctly on mobile devices. Specifically, the layout appears distorted, and some elements

      • Can i set per-client hourly rate in Zoho Desk and not to correct the calculation on invoice?

        We use Zoho Desk to run one ticket per client per month. All time entries go to the ticket, we have to enter hourly rate manually and then correct it when we do the invoicing at the end of the month. So, our workflow is as following: I worked for 30 minutes,

      • Unable to add Agents

        I am trying to add agents to my account. While filling the details and sending invitation, the system mentions that invitation is sent. But no email is received on the user side. I have tried this multiple times and have also checked Spam and other

      • How to add new widgets?

        Searched and searched and cannot find anywhere. Why is everything so hidden in zoho! Why is there not a button right here that allows me to create a new one, why is it buried somewhere else! Zoho's UI is so infuriating

      • Submit Ticket from Custom Form on Website

        Hi I would like to create new tickets from our custom form on our website including some custom fields like serial number. I would prefer PHP to create the ticket. I know there is the Zoho webform but we would like to create our own. I have now read into the API and with AuthToken this would work with PHP but it is deprecated  and will not be supported any more in the future, so this not an option. OauthToken on the other hand needs an interaction from the ticket creator (customer) which we would

      • Customising Sign Up Page in Zoho Help Centre Sandbox

        Hi, I would like to customise the Sign Up page in my Help Centre Sandbox Environment but when I try to access it I get this message: What setting or permission do I need to achieve this? Many thanks, Kunal

      • Sort data in Pivot Table

        Is it possible to sort by a data field. I can gruop and filter, but I culdn't find how to sort the results. Tank You.

      • How to interact webhooks with Creator?

        How can I interact webhooks from external websites with Zoho Creator?  I'd like to get notifications from external websites (Stripe, Zoho Subscription, etc.) These notifications are coming as HTTP POST request from those servers, on maybe daily, monthly or based on any events.  How should I prepare my app in creator to receive these requests? Where and how to should I program in Deluge if I'd like to add some part of the JSON/XML data to my form?  Thank you BR, Balazs

      • No Experiment Visitors

        I have an experiment running for five days. PageSense web analytics data shows the page is getting visitors, but the experiment data itself says zero visitors. I am in trial mode, not sure if that's related. A week ago, I contacted support through chat

      • How do I get at the data in "Partially Saved Entries"?

        Hi, Zoho Newbie here - I'm helping to support an existing Zoho installation, so this is all a bit new to me. I have to say, I'm liking what I've seen so far! We've just spotted that we have a number of respondents to our forms who don't end up submitting

      • SOLVED: Stopping Multiple Invitations when sync with Google Calendar

        I wanted to share this solution as I wasn't able to find it when searching through the Zoho community and via web search. The issue: When requestor books a meeting through Zoho Bookings, the requestor receives a confirmation email from both Bookings and

      • Help Needed with Creating Close % Reporting

        Now that our company has a good data set to work with we want to use ZCRM reports ways to track the performance metrics we have established. Specifically, I want to be able to calculate closing % for individual salespeople and individual support people.

      • Restricting Calendar View to Working Hours

        Hi: I'm trying to implement a calendar which displays all of my customer appointments.  Currently, the calendar shows all 24 hours of the day.  Is there a way to restrict the hours to simply the times my business is open? Thanks!

      • Static Prefill URLs Functionality in the App

        Hi, It would be great to be able to use the same functionality within the App, so create the Static Prefill URL as today and be able to use online as today, and then have an area within the App showing these Entries that can be pressed and opens the form

      • Outbound Gateway

        Hi, Is it possible to configure the Outbound Gateway to route external domains only and keep inter-domain emails locally delivered? When one of my users sends an email to another user within our own domain, I want user1@mydomain.com to user2@mydomain.com not to exit. However, if anyone within our domain sends to an external address, I want that email to be routed using the Outbound Gateway. Thanks. P.

      • Delivery Note Delivered item must be reduce in inventory stock

        When I create any Delivery note with product like mobile In our stock if it was 10 Unit I sold thru invoice, 4 unit And thru Delivery note, 2 Unit and I also change Delivery note status as delivered So in my stock it should display remaining 4 unit But write now it display 6 unit only. Please help me for that Because when I creating new invoice it display 6 unit in stock but actually in my physical stock its only 4. So I miss guide with stock display

      • Adding bills from docs *** Internal Error ***

        Same internal errors in Chrome & Edge !

      • Response time when adding customers to the database is increasing over time.

        Response time when adding customers to the ZoHo books database is increasing over time. The response time to retrieve a newly added customer is now 1.5 to 2 minutes. The database has approximately 2,000 customers. I think you need to reorganise the

      • Excluded transactions in Banking

        Why are the payees not checked when 2 payments are for the same amount to avoid exclusion? If there are 2 ( or more ) payment amounts which are the same then they are automatically excluded, this should not happen unless the payee names are the same

      • Introducing Zia AI in Zoho Show

        AI is no longer a distant concept. It’s one of our everyday tools, from answering casual questions to generating critical business documents. And presentations are one area where AI can be especially helpful. At Zoho Show, we’ve been deliberate in how

      • Plug Sample #10 - Simplify Ticket Management (Zoho Desk) with Chatbots

        Hi everyone! We're here with another simple yet effective plug for your chatbot to integrate with Zoho Desk. When a customer reports an issue/request during chat, it's logged as a ticket on Desk. When they return for updates, you end up searching through

      • Trigger a field rule when Choice Availability reaches 0

        First of all, thanks for shipping the new Choice Availability counter. It solves the basic “stop over-booking” problem. What’s missing, though, is a way to react when an option is sold out. Right now we can only disable/hide the choice; we can’t fire

      • Zoho People > Performance Management > Appraisal cycle

        Hello All I am using this 2 users to test out how it work on Performance Management User 1 - Reportee User 2 - Reporting Manager : Li Ting Haley User 1 : Self Appraisal Error How do i fix this error?

      • What's New - June 2025 | Zoho Backstage

        Plans change. People cancel. Tickets get handed off. It happens, and we understand. As an organizer, you need tools that offer flexibility for attendees while protecting your event’s integrity. That’s why we’ve built features to help you manage these

      • Include Article Sync Details in SalesIQ–Desk Integration Notification Email

        Dear Zoho SalesIQ Team, Greetings, We are using the integration between Zoho SalesIQ and Zoho Desk to sync articles from the Zoho Desk Knowledge Base into SalesIQ. As part of this integration, we receive the following email notification: "Your scheduled

      • Naming a Visitor in SalesIQ Messes up First and Last Name

        When I go to Visitor History to manually associate a visitor with a known contact, I press the pencil symbol next to the system-generated ID number. I enter first and last name, then email. Looks good so far. However, when it syncs with CRM, first name

      • Partial Sync

        Hi, got an issue with syncing cards across windows app, web app and iphone app. If I create a card and add some text content then everything syncs across all platforms ok. If I create a card and add an attachment, be it pdf, jpg or movie then the card

      • Related activity records for custom modules

        For default modules in CRM, whenever I create a task for a contact, the task also appears in the record for the parent account. How do I replicate this with custom modules? My specific situation is that I have a custom module as a child module to Accounts.

      • Why Do My Portal Users Can't See Any Data in Reports

        In My zoho crm i have created a button automation which basically is it converts a quote into invoice and sales order , so initially when a person who is my app user submits a quotation form it goes into quote module and record is created and in each

      • Introducing Zoho Commerce 2.0 — It's more than just selling!

        Hello! We are proud to launch Zoho Commerce 2.0, a reimagination of how online businesses look, feel, and function. This launch is both timely and symbolic, as we reaffirm our commitment to empowering small and medium enterprises with powerful, yet simple-to-use

      • Introducing prompt builder in Zoho CRM

        We’ve introduced a new way to put Zia’s generative AI to work—right where your teams need it most. With the all new prompt builder for custom buttons, you can create your own AI instructions to generate tailored content, suggestions, or summaries across

      • Item Batch Creation/Updation

        I have a requirement to integrate a local system with Zoho Books. I need to create items in Zoho Books with batch tracking enabled, but I couldn't find a specific API for that in the Zoho Books API documentation. Is there a dedicated API endpoint to create

      • Education Zoho User Group (ZUG) virtual meetup featuring Zoho Sign

        Hi there! The educational sector often faces the hassle of handling extensive paperwork, which leads to increased operational costs. A digital signature solution like Zoho Sign can help you modernize your processes, go fully digital, and seamlessly collect

      • Troubleshooting Delays in Zoho CRM Automation Workflows for Lead Status Updates

        Dear Zoho Community, I am refining a sales pipeline in Zoho CRM, implemented in May 2025, to enhance efficiency for a small business managing client leads. While the CRM effectively tracks leads, I am encountering delays in automation workflows that update

      • 📣 [Webinar] Spikra shows how businesses leverage Zoho Bookings to increase revenue

        [Webinar] Spikra shows how businesses leverage Zoho Bookings to increase revenue Hi all, Service-based businesses need to be on top of their client experience game to stay ahead. Spikra, one of our Advanced Zoho Partners, has been helping businesses deliver

      • Kaizen #172 - Leveraging the 'crmAPIResponse' Object in Queries

        Hello everyone! Welcome back to another week of Kaizen! We released the Queries feature sometime back and hope you have tried it out. A little gist about this feature before we move on to our post. Zoho CRM's Queries feature enables dynamic data retrieval

      • transforming 1D tables to 2D and the other way round

        Does Dataprep have tools to convert 1D tables to 2D tables and the other way round? The actions that are commonly called "pivot" and "melt". What I mean is transitioning between these two kinds of table: 2D id ____ name ____ surname ____ age 00 ____ Matt

      • How I Migrate data from one SharePoint Tenant to another

        I want to perform SharePoint tenant to tenant migration, but the problem is I don't know how to do so. I’ve heard about different SharePoint Migrator, but I’m not sure which one is the best for this type of migration. Any guidance would be really he

      • Rebrand your CRM with the all-new custom domain mapping setup

        UPDATES TO THIS FEATURE! 19th Jan, 2024 — Custom domain mapping has been made available for portal users in Zoho One and CRM Plus. 23rd June, 2023 — Custom domain mapping has been made available for all users, in all DCs. Hello everyone! We are elated

      • Next Page