Manipulating Multi-Module Lookup Field using Zoho CRM APIs

Manipulating Multi-Module Lookup 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:



      Zoho Campaigns Resources


        • Desk Community Learning Series


        • Digest


        • Functions


        • Meetups


        • Kbase


        • Resources


        • Glossary


        • Desk Marketplace


        • MVP Corner


        • Word of the Day


        • Ask the Experts


          Zoho CRM Plus Resources

            Zoho Books Resources


              Zoho Subscriptions Resources

                Zoho Projects Resources


                  Zoho Sprints Resources


                    Zoho Orchestly Resources


                      Zoho Creator Resources


                        Zoho WorkDrive Resources



                          Zoho CRM Resources

                          • CRM Community Learning Series

                            CRM Community Learning Series


                          • Tips

                            Tips

                          • Functions

                            Functions

                          • Meetups

                            Meetups

                          • Kbase

                            Kbase

                          • Resources

                            Resources

                          • Digest

                            Digest

                          • CRM Marketplace

                            CRM Marketplace

                          • MVP Corner

                            MVP Corner




                            Zoho Writer Writer

                            Get Started. Write Away!

                            Writer is a powerful online word processor, designed for collaborative work.

                              Zoho CRM コンテンツ




                                ご検討中の方

                                  • Recent Topics

                                  • Data Integration Platform

                                    Hi, Is anyone aware about a data integration platform like Dell Boomi that can work with Zoho Support? Any help will be higghly appreciated. Thanks Kunal
                                  • How do I pause or halt a running campaign?

                                    Hi, I set up an A/B campaign - and after testing, scheduled the campaign, I noticed an error in the subject line and had to pause or halt the campaign 'mid-flight' - could not find this, and the only option was to delete the entire campaign to halt the send (it was an emergency). Is there a campaign Pause or Stop function/button? I could not find it - am I missing something? (Thank you for your help  - I searched the resources and could not find an answer)
                                  • Always display images from this sender – Is this feature available?

                                    In Zoho mail, I had my "Load external images" setting set to "Ask me", and that's fine. That's the setting I prefer. What's not fine though is I always need to tick "Display now" for each email I get, regardless if I've done that multiple times from several
                                  • Payroll In Canada

                                    Hi, When can we expect to have payroll in Canada with books 
                                  • Real-Time Alert or Status Indicator for WhatsApp Connection Issues in SalesIQ

                                    Hi Zoho Team, We’d like to request a feature enhancement in Zoho SalesIQ related to WhatsApp integration stability and visibility. Recently, we encountered a critical issue where our WhatsApp bot stopped responding to messages without any warning or alert
                                  • Zoho Projects API 100 requests/2 min. Limit

                                    Hi Requesting clarification on the API documentation. "You can invoke or call an API for 100 times in a span of two minutes. If you invoke more than 100 times, the particular API request will be locked for the next 30 minutes. " Does this limit apply
                                  • Using the "Like" operator in Custom Formula

                                    HI there, Can someone please explain the way to use the "LIKE" operator in an IF statement to compare strings? I have tried the following but am not getting the results I'm after. if( "CurrentStatus" like 'Rejected*','Unsuccessful','Pipeline') Thanks Matt
                                  • Zoho Books | Product updates | June 2025

                                    Hello Users, We’ve rolled out new features and enhancements in Zoho Books, from the option to record advances for purchase orders to dynamic lookup fields, all designed to help you stay on top of your finances with ease. Introducing Change Comparators
                                  • Desk - CRM Integration: SPAM Contacts (Auto Delete)

                                    SPAM contacts is a useful feature, but when the CRM sync is used, it is very frustrating. When a contact is marked as SPAM on Desk, I wish to do the same on CRM. When a SPAM contact is deleted, I would like it deleted from CRM. The feature looks half-baked.
                                  • Writing SQL Queries - After Comma Auto Suggesting Column

                                    When writing SQL Queries, does anyone else get super annoyed that after you type a comma and try to return to a new line it is automatically suggest a new column, so hitting return just inputs this suggested column instead of going to a new line? Anyone
                                  • MS Teams Meeting to Zoho CRM

                                    Has anyone figured out a good way to push MS Teams meeting info on a trigger of "meeting end" to Zoho CRM? We're looking for a way to take attendees of a meeting and meeting duration and push it into Zoho CRM after the meeting has ended. If I can just
                                  • Action requested: Retain your sales journey configuration in Path Finder

                                    Dear Customers, We hope you're well! As you might know, we're completely overhauling our journey management suite, CommandCenter, and are in the last leg of it. As a means of getting ready to go live, we will be announcing a series of requests and updates
                                  • Running Balance in Account Statement.

                                    Running balance should come by default in the accounting statements but in ZOHO we need to customize every time to get the running balance in accounting statement. I did not understand, when the bank account statement opened from Bank Menu can show the
                                  • What's New in Zoho Inventory | January - March 2025

                                    Hello users, We are back with exciting new enhancements in Zoho Inventory to make managing your inventory smoother than ever! Check out the latest features for the first quarter of 2025. Watch out for this space for even more updates. Email Insights for
                                  • Marketer's Space: Bookmarks by Zoho Campaigns

                                    Hello Marketers, In this week's Marketer's Space, we'll look at a simple yet powerful feature that makes a big difference in your workflow: Bookmarks. Bookmarks is a built-in feature in Zoho Campaigns that enables you to create a personalized library
                                  • Knowledgeable Image Quality is very poor, any recommendations how to improve this?

                                    Hi All, We are looking at migrating our current knowledge base to Zoho so it can be kept in one location. Our current KB utilises a lot of images to try and make it easier for users and less wordy. Unfortunately, when I upload an image within an article,
                                  • Global Sets for Multi-Select pick lists

                                    When is this feature coming to Zoho CRM? It would be very useful now we have got used to having it for the normal pick lists.
                                  • Contact Segments with multiple CRM modules

                                    Hello, We have a somewhat unique setup in our system involving various components: Contacts, Accounts, Deals, and a couple of custom modules named Properties and Audit Logs. We're looking to implement a notification system via SMS and Email specifically
                                  • Cannot reorder fields in Page Layout in Expenses and Purchase Requests

                                    It is very inconvenient that the custom fields in Page Layout cannot be re-ordered. The only way is to remove the fields and re-create them; however, it is impractical. This would affect the reports and dashboards we are having. Not able to re-order the
                                  • Problem when forwarding emails

                                    When I want to forward an email received through Zoho, the layout changes: Buttons are cut Pictures change size Text changes alignment (left/right/center) Is this a common problem in Zoho? Thank you, Suzannah 
                                  • View Audit Trail field

                                    The Audit Trail feature is great, but its data is only available to admin users. It would be really great to have a system field "Audit trail" that we can add to the detailed view of a record. This would allow supervisors, directors and etc. to quickly track what changes have been done by whom for each record. It is a current feature from a client of mine and while it's probably possible to hard code it, since this data is already available in Zoho, I would be surprised to hear how hard it would
                                  • Recuring bills payments

                                    I've entered recuring bills that are auto drafted from my account monthly. Can I set up the recuring payment or do I continue to manually do it monthly?
                                  • Multiple Selection/Select All for Approvals

                                    I have a suggestion from users regarding Approvals. In our environment, our Regional Managers can receive multiple requests for Approval or Rejection. They find it tedious to approve (or reject) each individual record. They would like to have a way to
                                  • Automatically assign Contact Roles to a Deal

                                    Hi guys, Is there a way to assign multiple Contact Roles to a Deal via a workflow or similar? Thanks
                                  • Make record entry more organized with the Sections component in Wizards

                                    Hello everyone! Wizards in Zoho CRM have always helped you break long record-detail pages or large sets of fields into multiple screens, making data entry smoother and more user-friendly. Now, we’re taking a major step forward with a new Sections component—giving
                                  • Interactions Tab in Zoho CRM: A 360° Omnichannel View of Every Customer Touchpoint

                                    Hello Everyone, Hope you are well! We are here today with yet another announcement in our series for the revamped Zoho CRM. Today, we introduce Interactions Tab a new way to view all customer interactions from one place inside your CRM account. Customers
                                  • 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
                                  • Subfrom Changes are NOT included in Audit Logs and Timeline

                                    In the Timeline the subform changes are not tracked We have an important custom module for Recording Pricing Information It has a subfrom, now if Changes are made to the subform fields they are not shown in the timeline, ONLY the aggregated fields This
                                  • How to handle this process need using a Blueprint?

                                    See one minute screen recording: https://workdrive.zohoexternal.com/external/eb743d2f4cde414c715224fc557aaefeb84f12268f7f3859a7de821bcc4fbe15
                                  • on submit of creator form then record is create in Zoho crm purchase module then on automatically task want to create in the crm

                                    on submit of creator form then record is create in Zoho crm purchase module then on automatically task want to create in the crm
                                  • Zoho CRM Webinar – Automate everything across Customer Journeys in CommandCenter 2.0

                                    How efficient is your current CRM automation setup? As customer journeys become more dynamic, it's common for data and actions to get scattered across teams and modules. This leads to broken processes and inconsistent customer experiences—especially across
                                  • MULTI-SELECT LOOKUP - MAIL TEMPLATE

                                    Dear all how are you? We need to insert data from MULTI-SELECT LOOKUP in a email template, but I can't do that, when I'm creating the template I can't find the field to insert it. is there any solution? PVU
                                  • Changing the owner of a call

                                    Am I correct in my conclusion that I cannot change the owner of a call in Zoho? The field does not show up in the screen, nor can I make it show up as the systems does not give me that option. I cannot "mass update" it either. I tried it, but Zoho refuses to change the name of the owner. Please help out: how do I change the owner of a call.
                                  • Enhanced Candidate Portal: Now Featuring Federated Login, Passwordless Access & MFA

                                    You can now enhance your Candidate Portal experience with Federated Login, Password less Sign-in and Multi-Factor Authentication (MFA). These features offer greater flexibility and control—allowing seamless sign-ins through trusted platforms and adding
                                  • How to store API keys in zoho?

                                    Hi everyone, I'm currently building an integration using Zoho Flow and I need to securely store several API keys that will be used to make external service calls from my flows. I would not like to hardcode the values in the code of custom function. What's
                                  • Related Lists filter

                                    I have Contacts showing in our Accounts module. I customized the Contacts module with an Employment Status field, with the following picklist options: "Primary Contact", "Secondary Contact", "Active Staff(not a main contact)", and "No longer employed".
                                  • 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
                                  • Experience effortless record management in CRM For Everyone with the all-new Grid View!

                                    Hello Everyone, Hope you are well! As part of our ongoing series of feature announcements for Zoho CRM For Everyone, we’re excited to bring you another type of module view : Grid View. In addition to Kanban view, List view, Canvas view, Chart view and
                                  • 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
                                  • Next Page