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

      • Templates Access

        There should be an option to grant users access to templates but not allow them to edit/delete templates. In setup there is only one tick option for templates. This will give any user access to view as well as delete/edit. This doesnt make sense as they

      • Generate a Zoho Sign link

        From time to time I get a response "I never received your you e-document for electronic signature" is there a way to generate a Zoho Sign link to share.

      • Power of Automation :: Autocomplete the Project upon Task closure.

        Hello Everyone, A Custom function is a user-written set of code to achieve a specific requirement. Set the required conditions needed as when to trigger using the Workflow rules (be it Tasks / Project) and associate the custom function to it. Requirement:

      • Unable to send email through Gmail

        So I had a custom domain email from Zoho and I was able to send emails from this account through my gmail. 2 days ago I added another user. This user is not able to receive any emails, that's the first issue, moreover, even though I haven't changed anything else other than adding this user, now I am unable to send email through my gmail account with the first user either! I have opened a case with priority "I am stuck, need assistance", haven't got a single reply in about 36 hours. I am unable to

      • "Invalid Credentials(Failure)" when configuring IMAP (Outlook)

        Getting the below response when attempting to configure Zoho mail in Outlook 2016: Notes (what I've done so far): Zoho mail on web client is working with no issues. Though I was certain the username & PW were correct (was using same credentials on web client as I was attempting to utilize in Outlook 2016), just in case, I went ahead and changed my password on the web client and re-attempted Outlook configuration; same error response. IMAP for my email account was enabled on the web client (and POP

      • Custom service report or Zoho forms integration

        Hello, So far the experience with Zoho FSM and the integration with Books has been good, however there are limitations with service reports. As with my business, many organisations send technicians to different types of jobs that call for a different

      • Pre-fill Email field on Zoho Forms

        Hello there, How do we automatically pre-fill the email address field of a Zoho Form from the data that is in CRM? Thanks, Joel

      • Webhook Trigger for New Messages in Cliq Channels

        Hello, I would like to request a feature to enable webhook triggers when a new message is added to a Cliq channel. This functionality would allow us to seamlessly send important information from Cliq to other relevant systems. This webhook trigger can

      • Unable to add subdomain email account under the main email account

        Hi, Is it possible to add a subdomain email account, like sky@agent.rebrightrental.com from the Admin Console of admin@rebrightrental.com in Zoho Mail? Or is that not possible? I want to create at least 3, like oak@agent.rebrightrental.com, bliss@agent.rebrightrental.com,

      • How to delete a large number of emails

        Since no one else seems to be asking this, there must be something in the zoho mail interface that I am failing to see. Not looking for an automatic method. Instead, when I sort email by sender, I want to be able to select all emails from a sender and

      • want to renew my account

        I am not getting email - it seems renewal of account is required. pls check and advise how to renew the account and what would be the charges

      • Mail app and desktop on chrome not syncing properly.

        Yesterday I spent a significant amount of time on the computer moving emails to different folders, and deleting several. This morning, I realized on my zoho mail app it still showed all the emails in the inbox. Nothing had synced. I couldn't find a sync

      • Can't connect to Thunderbird

        Setting up Thunderbird I get an error message: "Unable to log in at server. Probably wrong configuration, username or password". The password and email address are definitely correct as I used them to log in to webmail. My settings are definitely correct

      • Can't receive emails, but can send

        I setup a mail using the domain @shopik.io. I set this up using the correct CNAME record on Namecheap. When I tried to send a test mail from my Gmail account it was not able to send and I got the following error; The response from the remote server was:

      • Unable to send message;Reason:550 5.4.6 Unusual sending activity detected. Please try after sometime

        Hello i'm unable to send any email because i keep getting this error Unable to send message;Reason:550 5.4.6 Unusual sending activity detected. Please try after sometime i have literally sent less than 10 emails today i'm not sure why i'm getting this

      • Tickets are enabled but not showing in zoho desk widget

        Hi, I have a Zoho Desk ASAP JWT widget inside my app. I enabled the KB, tickets, and salesIQ chat (screenshot 1), but only the KB and chat are showing on my app widget (screenshot 2). Can you help? Thank you

      • default to display images in mail

        How do I set my mail settings to default to display images, rather than asking me each time I open a message? Thanks, Sup

      • Zoho CRM Theme Color?

        I've read multiple articles stating it's possible to change Zoho CRM theme colour (top menu bar) from personal settings menu, however, my zoho has no options for this at all and I've looked everywhere........has this feature been removed? I'm currently

      • US Zipcode Mapping for Sales Tax areas

        In its current form, Zoho Commerce maps tax percentage to different states. Due to the wide variety of tax areas within each state, it would be much better to map sales tax against each individual zip code. In addition, it would be highly desirable to

      • New Emails not being received in Zoho Email account

        I have built a new website for my client, who has an email address like his_address@zohomail.eu (example). When his customers use the Contact Form on his website, the notification emails are sent to an address as his domain name, and the Webhost automatically

      • Custom Function : Copy multilookup field to text field

        Hi, I'm a newbie on function programming, I try to copy text from a multi lookup field named "societe" to a text field named "societe2". I've used this code. In deluge script it seems to work, but when I trigger this function it doesn't work (Societe2

      • Relocating the server from Europe to the UAE

        We are experiencing issues with the sales templates and attempted to collaborate with the companies you recommended to assist with the templates. Unfortunately, we were unable to add their email addresses to our panel due to an error (The ERROR is: USER

      • get statement as file pdf to send in whatsapp template

        hello i have the following url which sends an email with the statement attached sendStatement = invokeurl [ url: "https://www.zohoapis" + dc + "/books/v3/contacts/" + customerID + "/statements/email?start_date=" + start_date + "&end_date=" + end_date

      • I already configured DKIM Records, and other records as well

        I already configured DKIM Records, and other records as well but it is still going like a spam mail

      • No recibo correos

        Buena tarde. No estoy recibiendo correo en Zoho mail, pero si puedo enviar. Como puedo solucinarlo?

      • Email not sending on Iphone on (1) account. Works with the others and set up thesame.

        When I attempt to send an email on one of our accounts on my iphone, It doesn't and. then comes back with an error message.. I've reviewed my other two accounts, and they both work fine on my iphone, it's just this one account.. I've also looked at the

      • Receive the incoming emails of my users

        Guys, I need some help. As an admin, can I receive all the incoming emails from my users?

      • I couldn't create new email "connect@cafeconnet.lk"

        Dear Manager, I want to create new email "connect@cafeconnect.lk" but I can't do that. Please help me for that.

      • didnt add my soho account Mail

        i cant add my soho account arturo@thrivechile.com in Mail (apple)

      • Zoho Projects > Workdrive Integration - Where can you find your files in Workdrive?

        Following the instructions here: https://help.zoho.com/portal/en/kb/projects/integration/zoho-apps/articles/zoho-workdrive-integration#Benefits Put a file in the Documents section of a Project. Then Trying to navigate to the Team Folder in WorkDrive and

      • How to set custom Sales Order numbers

        I am trying to create Sales Orders with data from Jotform submissions. Auto number generation is disabled within Books. Whereas the flow Input recognizes the number (40732 in this example), the Output does not. How can I fix this? I'd like the number

      • Zoho desktop problem when using 2 displays

        I have a Microsoft Surface Pro with a second display attached. When I open Zoho mail desktop and place the window on on the second display and I keep the display attached, everything works fine. HOWEVER: when I then detach the second display (the Zoho

      • Assign Multilpe Owners to a Single Deal and Split Revenue Between the Two

        Hello, In our business, it is common for 2 sales reps to co-manage a deal. As such, I would like to add 2 co-owners to a deal within CRM, and then split the revenue generated by a deal between both owners in our analytics. We are currently tracking this

      • Mix and Match Email Plan

        Dear Zoho Sales Team, I hope you’re doing well. I am currently subscribed to Zoho Mail Premium with one account. However, I would like to modify my plan by adding two Mail Lite (10GB) accounts alongside my existing subscription. Could you please confirm

      • Comprehensive guide to add users

        We've received quite a few questions regarding adding users to the Zoho Sprints workspace. So we decided to address it through a comprehensive post covering the locations (modules or tabs) from which you can add your users. Adding users to your workspace

      • How to monitor hybrid projects?

        Hybrid project management sounds great, but, with projects being run on different project management methods, how can we monitor the overall progress and derive insights from them? If you've got this question as well, Zoho Projects Plus’ dashboards have

      • Learning how to customize templates via code and best practices

        Hi! Our developers team want to learn how to edit our template files safely. The last time we messed with these files our site went down for a day and we had to reconfigure it from scratch. What are the best practices to do this? How can we get a template

      • ULAA threat

        My Sentinal One app just killed ULAA as a threat. I reinstalled, killed it again. I opened ZohoOne CRM in Chrome it worked however it was a least 1 if not 2 backsteps from the version I'm using. Is anyone else having this exerience?

      • Seventh Insight - Organize your data using Modules

        The Wheels of Ticketing - Desk Stories Organize your data using Modules What are Modules? Modules in Zoho Desk are powerful organizational tools that facilitate efficient help desk operations. There are eight standard modules, each designed to manage

      • Argument Mapping went missing?

        How can I access the IDs from the mass action button when argument mapping is unavailable or missing?

      • Next Page