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

      • Truesync for Linux

        Is Truesync available on linux ?

      • Web access blocked

        Hello, My account (chris@thewebprojects.com) has been blocked due to security reasons. Please see attached. Can you kindly please help me. Thank you in advanced

      • How to determine ZohoCreator organization ID

        I am trying to setup an API to interface with my ZohoCreator app by following the self-client credential flow here https://www.zoho.com/accounts/protocol/oauth/self-client/client-credentials-flow.html However, it requires me to input my organization ID.

      • Autofill Zoho form with Zoho campaign data

        Hello, I send campaigns and we have set a button called "Demo" in that campaign. This button leads to a form. Since we have the data in Zoho Campaign, would it be possible that some fields of the form (first+last name, email, company) are automatically filled when our readers click on this button? If yes, how could I do that? Thanks Aurélie Leyendecker

      • Need to be Amount Adjusted with same Group Comany

        Dear Sir/ Madam, Good Day, Example wise i write my quire Below A B C & D E F Bothe are Same Group Companies We Paid 50000 AED to ABC Company but we received Invoice 48000 AED worth of material Balance 2000 AED invoice i received from D E F. I Need to

      • Transfer between 2 accounts in forein currency

        Hello, While abroad, I have exchanged some money in a money exchange service from a foreign currency (MYR) to another foreign currency (USD) without passing through my base currency (CHF). How do I record this transaction in Zoho Books? When I try to

      • Zoho Books Webhook in Custom Module doesn't work

        I have a custom module "Purchase Request" in Zoho Books in which we're trying to convert status of the PRs to Draft and Pending Approval. We've explored different applications and custom functions but found that the status is not "writable". However,

      • Issue with Missing Scope for Creating Service Report via Zoho FSM API

        Hello @Latha Velu , I am currently working on creating a connection to create a Service Report in Zoho FSM using the API. However, while configuring the required scopes, I noticed that the scope ZohoFSM.modules.ServiceReports.CREATE which

      • Imap Support?

        Does Zoho Books support IMAP? I have enabled outlook integration from settings in Zoho Books Yet the emails I send from Zoho Books for example if I email a purchase order or an invoice I dont see them in it in my sent box in outlook Is there a problem

      • ADDING FUEL SURCHARGE & HST

        Hello I need to invoice the customer showing both Fuel Surcharge & ON HST separately. The FSC should be 20% of the subtotal. The HST should be applied to sum of Subtotal + FSC So it should be like: SUBTOTAL: 100.00 FSC (20%): 20.00 HST (13%): $15.60 How

      • Zoho Project API search?

        Good day, i would like to search our entire portal for a task using the API. We have over 20k tasks so I dont to search for all tasks and then do a for each as it would take way to long and also would need to go over the limit of 200 records per query.

      • Handling Deposits to Vendors and how to book this

        Our scenario: 1. We rent equipment from a renting company for a project (Vendor "Eurorent") 2. We receive an order confirmation with a request to pay a deposit of € 1500. (this is not a Bill) 3. We pay a deposit of € 1500 for the equipment. 4. After using

      • Tip of the Week #61– 5 easy ways to declutter your inbox!

        Managing a shared inbox is easier than you think. With the right tools and a smart approach, your team can stay on top of every conversation, collaborate more effectively, and deliver timely responses without any unnecessary back-and-forth. Here are 5

      • Vertical Solution Zoho One

        Hello, is it possible to create a vertical solution for Zoho One? Just like it is possible for Zoho CRM?

      • Multiple workspaces with in Bigin CRM

        As a freelancer working as a sales representative for two companies, each with its own email address, I would like to know if it’s possible to have two separate workspaces in Bigin. This way, I could manage each company and its contacts independently,

      • Allowing subqueries in FROM clause

        When building a Query table in Zoho Reports, I encountered an error when attempting to put a subquery in the "FROM" clause of my statement.  Why isn't this currently supported?  Is there a plan to implement this functionality in the future?

      • CRM for Everyone - More Actions Option to Create Record

        Please consider the option create a new record for the module from the More Actions menu. I know there is an "Add New" icon further down the menu to create a record for any module, but this just seems more intuitive and could reduce the need for the "Add

      • Zoho books partners: Transferwise, Resolut

        Can anyone tell me if Transferwise and/or Resolut (payment systems) are in integrated?  I know PayPal and Google are, but in Europe we like Transferwise and Resolut is an up and coming multi-currency app. Xero and Transferwise are fully compatible. Thanks

      • Getting oauth errors on bigin

        Hi Support, I'm getting oauth errors on bigin even though it works fine with CRM. I created a self client which will add contacts. I gave every permission you could and it still didn't work. What should I do. I might just switch to the standard CRM since

      • Assessment Field in Custom View

        Zoho recruit finally added the ability to filter Job Applications by Assessment Answers This is a very valuable addition to the Recruit But this is currently missing from the custom view This should be added to the custom view as well

      • Name Change and Delete Email ID and Alias

        Hello please i require urgent assistance, 1.) I would also like to change the name that appears when people receive my emails. I have an info@spacetraiders.com but when people receive my email its say Ronma Adedeji instead of either Info or Space Traiders..

      • Feature Requests and enhancements: Subform

        By The Grace of G-D. Hi, It would make it much easier to use if we could have some more features in subforms: More Columns/Fields Set the size of a column Show the subform in Full Page Width Sorting By Column Please consider The above suggestions. T

      • Unapplied AP Credits not showing up on AP Detail Aging

        I am new to using Zoho Books. I was reconciling some accounts and found differences from the GL balance and AP Aging and it came down to unapplied vendor credits. Is there an option to include that on the report, so I can pull a matching AP Aging to the

      • Add Entry and Subform Record from Deluge Scripts

        Hi all,  I would like to know how do I add a new entry and also subform records from a deluge scripts.  I can use the insert into to add a new entry to a form, but how do i insert a collection into the subform of the entry? I am using a deluge script

      • Finding draft ticket replies

        Is there a way to see all tickets which have draft replies?

      • How to apply a tag to a ticket based on the to email address?

        I need to assign a tag to a ticket if the ticket was sent to a specific email address. For example, we have the email accounting[at]company.com forwarding into Zoho Desk. We would like all emails that were sent to this address to be tagged with an Accounting

      • Engineering Change Order Process using Tickets?

        Hi Zoho Community, I'm working with my company to create an Engineering Change Order/Request (ECO/ECR) process where engineers can internally create tickets for changes in a product that must be reviewed, approved and implemented by people or teams in

      • How can I move a ticket from Department A to Department B?

        Hi there, how do I move ticket from Department A to Department B? I went in the ticket and tried to scroll down the menu under the "department" but it won't let me, I am a support admin. Did I do anything wrong? or am I doing it in the wrong place?

      • Validation Rules Trigger on Untouched Fields

        In Zoho Desk, validation rules trigger for ALL fields during an update—even fields that weren't modified in the current edit. This behavior is fundamentally different from Zoho CRM and other Zoho products, where validation rules only apply to fields actually

      • How to work with getFieldNames formdata functions ,Any Examples

        I don't find any example showing usage of getFieldNames. Where do i find .is there any Help documents available

      • Zoho Notifications - Received two notifications for one message and none for the other

        We had a client reply to a ticket twice in one minute. The ticket owner received two emails for the second message but none for the first (which was crucial content and unfortunately was therefore missed). I'm assuming this created a race condition -

      • What is the difference between "Reply" and "Public Comment" in a ticket?

        Hey, my company is thinking about switching to Zoho Desk but we do not understand the difference between the "Reply" and the "Public Comment" feature. When should we use which? And why? What is the difference between them? Thank you for your help! Kindest

      • Tasks View for Opportunity/Jobs does not indicate "Related To" account

        How can ZoHo be setup so that when a task is created for an Opportunity, the subject automatically lists the underlying account? Right now, it's impossible to link the Account to the task when the task is created from the Job.  Therefore, the open task view is inadequate.  And it's a lot of maintenance to have to manually add the account to the subject...defeating the purpose of "Automated" workflow. 

      • can i show alert when i finish running the function?

        how i can show alert inside the custom function or popup notification. when i use alert inside the custom function it show this error Error at line number:  2 'ALERT' task can be used only in on load, on validate and on change actions ​

      • CRM calendar not syncing with Zoho Calendar

        The sync is not happening: This is my Zoho Calendar CalDAV synced with Outlook This is my Zoho CRM Calendar (sadly empty ...) I have enabled CalDAV Access. In Zoho Calendar, I have set up APP Calendar sync like this: What else can I check? Thank

      • Pipeline in Custom Modules

        I love the way the Sales Pipeline looks and functions with reports. I would like to add the save pipeline features and visualization to a custom module, however, I only see that these pipelines are only available for the Deals module. Is there a way to add pipelines to custom modules?

      • Cannot associate event with other objects when creating?

        I am attempting to associate an Event with one or more other objects when creating it via the API. According to the API docs, the "Related_To" property is a jsonobject even though the description says "Provide the details about the entities the event

      • How to disable subform records dynamically

        Hi Everyone I have a requirement to dynamically disable or hide subform fields based on certain criteria. However, the code I tried didn't work as expected. It either disabled or hid all the fields in all subform records or none at all. What I actually

      • Client Script Operate Timeout

        Hi Zoho, I have set a client script that use for ( i =1; length < i , i++) to fetch all of the product in order I have an order have 30+ products, seems this script will be stopped when it is checking rough 10 + products because of timeout (may be). May

      • Why and When to Manually Regenerate Reports?

        What is the protocol for needing to regenerate reports?  It is very confusing when data in reports pulls correctly sometimes, but are inaccurate other times.   Why is report regenerating necessary at all - can the report function not read the live data as inputted into the forms?  We have built lots of reports and it is very tedious and time consuming to have to regenerate the report before each use of that data to make sure it is accurate.  Is there a way to know when a report should or shouldn't

      • Next Page