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:


    • Sticky Posts

    • Kaizen #217 - Actions APIs : Tasks

      Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

    • Kaizen #216 - Actions APIs : Email Notifications

      Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

    • Kaizen #152 - Client Script Support for the new Canvas Record Forms

      Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved

    • Kaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script

      Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.

    • Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI

      Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the

    • Recent Topics

    • Narrative 1 - The significance of a business account

      Behind the scenes of a successful ticketing system - BTS Series Narrative 1 - The significance of a business account Setting up a proper business account is a crucial step that is often overlooked when launching a ticketing system for your service company,

    • Changed hosting for domain, Zoho mail stopped working.

      I have changed hosting fro my domain and from that time my zoho email stopped working

    • we need to add a Customer Number field to the PDF document templates

      Hello everyone. We are currently using Zoho Inventory for our small business operations and have found it to be a valuable tool. However, we’ve encountered a specific requirement: we need to add a Customer Number field to the PDF document templates (such

    • Joining Two Reports

      Hello Guys, I have three modules: - Orders - Custom module - Clients - Contacts - Basic Pay I am using the order module to store the revenue share amount for each order which will be paid a sales rep The Orders are child or clients so I am pulling a report

    • Power of Automation :: Notify users Automatically when @Mentioned in Tasks Description

      Hello Everyone, A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate

    • Recording a payment in foreign currency not allowed

      Hi, my base currency is CHF. I made an invoice in EUR, which have been paid with an extra amount (which are the fees I guess). When I record that payment from the invoice page, I can select the EUR bank account. But the amount received is above the invoice

    • Introducing WhatsApp integration and quick editing capabilities in Zoho Sign

      Hi there, Zoho Sign already helps users collect signatures via email and SMS, and we're happy to announce that you can now send documents and authenticate recipients right through WhatsApp. Some of the key benefits include: Communication with recipients

    • Order Wise Expense Tracking and Reporting Possible?

      Hi, We are a manufacturing firm and take up several orders at the same time. Each order will be associated with a single sales order and then once completed to a single invoice. When recording expenses, is it possible to associate each expense with a

    • Layout Rule Fields Appear in "Verify Details" Pop-up — Confirmed Working

      Hey everyone — just wanted to share a quick discovery. I created a Layout Rule in the Deals module that makes two fields show up (and required) when the stage is set to Closed Won or Closed Lost — one pick list and one text field. To my surprise, those

    • Can you please let us know how we can use Zoho for multi store?

      Hello Team, Can you please let us know how we can use Zoho for multi store because when we connect our plugin to Zoho and we create a product and then on another store when we create product with same name then product already exist error occurs, so how

    • Zoho One Home Dashboard - My Tasks (Projects) & My Overdue Work Items (Projects) have no data.

      The title basically covers the situation. I've set up the dashboard cards, and for a while, they were showing data. Now, they are both blank. Is anyone else experiencing this, or has anyone else experienced this, and if so, is there a fix?

    • Zakya - Release in North America?

      At Zoholics it was pitched like Zakya was already released in North America. However, when looking for it I couldnt find it. There isnt an integrated app available in Zoho. I figured maybe it was being released at Zoholics. Now over a month later, its

    • Custom Field Mapping in Outlook

      I have 10 custom fields in Zoho is there a way to create and map them to the outlook contact?

    • Custom module - change from autonumber to name

      I fear I know the answer to this already, but thought I'd ask the question. I created a custom module and instead of having a name as being the primary field, I changed it to an auto-number. I didn't realise that all searches would only show this reference.

    • Enhanced Zoho CRM and Office 365 calendar synchronization features!

      Dear customers, We're excited to share some significant improvements to our Office 365 calendar synchronization features, aimed at providing you with more control and a more personalized experience. What’s new Choose your Office 365 calendar: During the

    • Problemas de usarmos no Brasil

      Somos usuários a exatamente um ano do Zoho Recruit, agora migramos para o Zoho One. Temos enfrentado por diversas vezes problemas da ferramenta não estar realmente preparada para funcionar corretamente na lingua portuguesa. Problema esse não específico

    • CERTIFICADO DIGITAL - BRASIL

      Olá, Temos o ZOHO ONE e no Sign vemos de forma simples a assinatura digital, temos nos BRASIL certificado digital, de no CERTISIGN homologado pelo GOVERNO do BRASIL, há possibilidade de gerar a assinatura diante deste certificado?

    • Zoho Duplicate Reference Numbers

      I have 2 accounts through zoho. On one account if I enter a bill with the same number as a previous bill I get a warning message saying that there is already a bill with this number. However on the other account I do not get this message. How do I turn

    • integration between Zoho Site and Zoho Learn

      integration between Zoho Site and Zoho Learn so that when a user registers on the Zoho Site, their account is automatically created in Zoho Learn!! the use case i have pro plan in zoho site and zoho learn and i have puted the zoho learn domain in zoho

    • Automation #6 - Prevent Re-opening of Closed Tickets

      This is a monthly series where we pick some common use cases that have been either discussed or most asked about in our community and explain how they can be achieved using one of the automation capabilities in Zoho Desk. Typically when a customer submits

    • Not able to list or add contacts

      I am not able to get a list of contacts via api request. Tickets for example are listed via api even without orgId, so it shoud be similar. What is missing to reach the requirement. My aim ist to add a contact via API and then add a ticket with the contact

    • See contrat information from an account under the ticket

      Hi there, How can I program something to display created and selected contract on the ticket itself so my agents see it and can support correctly according to the contract and SLA ? Thank you :)

    • Weekly time log view

      The Weekly Time Log view is pretty nice. My users really like it when I show it to them. They like being able to pin ongoing tasks. Anyway, it's sort of hard to find. It is grouped with the Add Time Log button as a pull down. In my opinion, it should

    • Any Impact of Amazon Listings API on E-commerce Integration?

      Amazon sent the following message about changes to their APIs. Our only Amazon app / integration is Zoho Inventory's eCommerce for Amazon US, so the message below in bold gives us concerns about if Amazon's warning is referencing Zoho's Amazon US integration.

    • Working with Products that are non-tangible

      How does one create a 'service' in products? Is there a way to disable inventory functions for things like Sofware as a service? The services module doesn't look to be much help either. Not sure how to do this in CRM

    • ePOD Devices

      Has anyone tried and tested and devices that deliver ePOD (electronic proof of delivery)? We would like our drivers to use an ePOD device to get the customer signature The app should then be capable of updating the sales order to show delivery.

    • API Integration

      Why are we unable to do API Integration for Job borads

    • Remind/Recall Document API

      When I recall a document through the Sign API, I would like to be able to specify the reason that gets sent in the user notification email. Same with including a unique message when sending a document reminder through the API. Is there a way to include

    • Zoho Books API Creating Invoice and Address API

      I'm trying to create an invoice with zoho books api and i get the following error: Error creating invoice in Zoho Books: { message: 'Request failed with status code 400', details: { code: 15, message: 'Please ensure that the "billing_address" has less

    • Convert Multiple PO in 1 Bill

      Does anyone know how to convert multiple POs in 1 Bill? Thank you

    • merge the Multiple POs to single PO if Vendor of PO"s --in Zoho Inventory

      HI Merge the Multiple POs to single PO if Vendor of PO"s are Same ----in Zoho inventory Please provide any work around to achive this .

    • How to add categories to community

      In my Community, I would like to add several Categories but I don't readily see how this is accomplished. Currently, I have one category in my community with several forums. But I would like to add more categories. Thanks.

    • 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,

    • Assistance Required: Displaying Dynamic HTML Table in Zoho Creator Dashboard Page

      I am currently stuck while creating a custom dashboard page in Zoho Creator. I want to display a designed HTML table showing Teacher Registration data with this condition: If Total Allowed Leaves < 10, display those teachers in the table. Page Scripts

    • Visibility of Custom Questions in the Question Pool

      A colleague is adding our own questions in the question pool for our Employee Engagement survey, but I can't see the questions she has entered, even after refreshing the webpage. Are the custom questions in the question pool only visible to the one who

    • campaigns contact lists not exporting

      I'm trying to export a specific lead source from my contract list in 'campaigns'. Every time I have to do this the contacts won't export. I have done a search and selected the specific contacts I want to export. The box appears to choose the file type,

    • Recipient Field on replies doesn't update with Contact change

      Some emails that come into our system come from an online form and the sender address is a noreply@whateverthedomainis.org So in order to reply to the original sender, we need to update/change the contact for the tickets. However, after we change the

    • Multicolumns fields for native forms

      It would be nice to be able to create forms with multiple columns. Currently, each field occupies a single column, which makes a fairly complex form seem too long.

    • Assign values to hidden fields in native forms

      It would be great to be able to assign values (static or dynamic) to hidden fields in a form. Currently, I can only assign a value via the URL. I currently have a form integrated with a webhook, but I don't have a way to send useful form data as parameters,

    • Migrating Email Content to a Shared Mailbox Address

      I am moving my email to Zoho Mail (currently hosted through GoDaddy). I have created a user (me) and I have also created a "Shared Mailbox" Group (through the admin panel) with an email address I will be using as an organization address. My personal email

    • Next Page