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:


    • Recent Topics

    • Problema para enviar y recibir correos

      Buenos días, mi cuenta de correo secretaria@construccmauro.com presenta problemas y no me permite ni me envía ni recibe correos, me sale este error.No fue posible enviar el mensaje; Motivo: 554 5.1.8 Correo electrónico bloqueado saliente.  Aprende más., Agradezco

    • Legit email address?

      Hello, I received emails from zohoadmin@biznetvigator.com with a password expiry notice. is that a legitimate email?

    • 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

    • SMTP Authentication Fails with App Password – “535 Authentication Failed” Error

      Hello, I'm trying to send transactional emails from my WordPress website using the WP Mail SMTP plugin with Zoho Mail (smtp.zoho.com on port 465 with SSL). I've created and used a Zoho Mail app-specific password for SMTP, and verified that: The email

    • Deluge script issue : Mismatch of data type expression. Expected BIGINT but found STRING

      I'm building a Zoho Creator form to take inputs for Email, Bootcamp Name, and Tag. If a record with the same Email + Bootcamp exists in a custom module (bootcampattendence), I want to update it by adding a new tag. If it doesn’t exist, I want to create

    • how to integrate zoho bigin to wordpress website ?

      hello , i want to integrate zoho bigin to wordpress webiste , can anyone help me with the tutorial ?

    • Survey end date extension

      Hi, Is there any way to extend the end date of my survey? I needed more time in finding respondents that is why I need to extend the end date of my survey. Help. Thanks

    • Empowered Custom Views: Cross-Module Criteria Now Supported in Zoho CRM

      Hello everyone, We’re excited to introduce cross-module criteria support in custom views! Custom views provide personalized perspectives on your data and that you can save for future use. You can share these views with all users or specific individuals

    • AutoScan Not Working Since April -Support says it with engineering

      Hi there, Autoscan has not been working on my account since April. Without this feature, completing expenses reports is laborious and error-prone. I keep asking for updates seeing as this is a critical feature, but told that it's being looked into and

    • Problem with signature in a forwarded mail

      Dear All, In my email account I created a signature and I unchecked the 'Place signature above the quoted text for relies and forwards' My question is, when I am trying to forward an email, sometimes I need to insert my signature so I select it from the

    • Out of Office not working

      I have set up out of office on zoho mail, however, it does not reply to every mail sent to it. I have tested it by sending several test messages from multiple different email accounts, I will get a response to some of them, but not all of them this is

    • Error message that says only images and no text

      I filled out a template for a weekly newsletter with text and images throughout but when I click save and next an error message comes up that says "Campaign content has only images and no text" which is not true at all. I have no idea how to fix this issue and don't know where the problem is. 

    • Link project invoices to sales orders

      As a business owner and project manager I create estimates with my clients which then become sales orders. When billing for project work I want to invoice against the agreed sales order. I see that I can create invoices and link them to sales orders in

    • Contacts Don't Always Populate

      I've noticed that some contacts can easily be added to an email when I type their name. Other times, a contact doesn't appear even though I KNOW it is in my contact list. It is possible the ones I loaded from a spreadsheet are not an issue and the ones

    • Cannot add zoho email to gmail acc

      I'm trying to set up my zoho mail to connect to my gmail acc but no matter what I try I always get this problem. What should I do now? Password is up-to-date. Authentication failed. Please check your username/password. [Server response: 535 Authentication

    • 553 Relaying disallowed - Invalid Domain

      I have this error "553 Relaying disallowed. Invalid Domain" when sending an email to any email address. But I still receiving email from other emails. I checked MX, DKIM, SPF and it's ok. Could you check and help? Thanks

    • Function #25: Automatically generate purchase orders from a sales order

      We kicked off the "Function Fridays" series with the goal of helping you automate your everyday accounting tasks. As we delve into today's post, I'm delighted to announce that we're here to present the 25th custom function in this series. While it is

    • Turn off Organization Contact List

      We need to be able to turn off the Organization Contact list for some of our staff. Once the Organization Contact list is turned off for a user, we would then like to be able to create a list of contacts on per user basis that would not be editable by

    • In the Blue Print Transition requirement received it will show 8 check field in pop up if they any one of this field then only move to next stage Ist quote

      In the Blue Print Transition requirement received it will show 8 check field in pop up if they any one of this field then only move to next stage Ist quote Pls help how i fix this

    • Unable to send massage Reason 553/ Relaying Disallowed. Invalid Domain

      Cant sed massages from my email. All massages from my domain received the same issue Unable to send massage Reason 553/ Relaying Disallowed. Invalid Domain

    • Kaizen #194 : Trigger Client Script via Custom buttons

      Hello everyone! Welcome back to another interesting and useful Kaizen post. We know that Client Scripts can be triggered with Canvas buttons and we discussed this with a use case in Kaizen#180. Today, let us discuss how to trigger Client Script when a

    • Issue with POST request creating Calls in CRM

      Hello, I am in the middle of integrating some 3rd party Call center API with Zoho CRM and going through our logs I see some discrepencies. We sometimes get an error: {"data":[{"code":"INVALID_DATA","details":{"api_name":"Call_Duration","json_path":"$.data[0].Call_Duration"},"message":"Please

    • 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

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

    • GSTIN Public Search API

      Does zohobooks have an api using which i can search GST numbers and get their details?

    • External @zoho.com mail stopped working today, yesterday no issues

      Hello, Over a sudden mail stopped being delivered to inbox. Domain is standard zoho.com worked no problem yesterday, today nothing in inbox. Sent several test emails from corporate account & from gmail.com, logs show acceptance by zoho mail server, but

    • I wan to schedule a meeting report From previous Thursday to this thursday of this week on Every 6 pm want to recive this report in zoho CRM

      I wan to schedule a meeting report From previous Thursday to this thursday of this week on Every 6 pm want to recive this report in zoho CRM. How I Can achive this in Zoho CRM.

    • Quotes

      Has anyone figured out how to automatically upload a quote that was signed via Zoho Sign and insert it directly to that leads file and push it through the pipeline to proposal signed status?

    • Suggestion: Smart Purchasing Module for Zoho Inventory and Zoho Books

      Suggestion: Smart Purchasing Module for Zoho Inventory and Zoho Books As an active user of Zoho Inventory and Zoho Books, I’ve noticed that the suite already provides valuable tools for managing inventory, analyzing trends, and processing purchase orders.

    • TDS Filing

      Is there any option for automatic 26Q and 24Q filing in Zoho books. Even Tally has this option. Why don't Zoho has this ? Is there any customisation available for this ?

    • Adding bank details to the contact through API

      How to add bank-related information to the contact while creating it using API? The account number needs to be encrypted before sending it through API but not sure how to encrypt and get those values. Please guide me in this.

    • average cost display

      Hello there, I'm using the average cost valuation method, and the cost price shown in the Items menu should reflect the latest WAC (Weighted Average Cost). However, it doesn't update automatically. Is there a way to display the current average cost without

    • Apple Mail issues

      Dear Sir or Madam, I am trying to configure my Zoho mail account to Apple Mail. It is not working. It seems to need more information (perhaps a path prefix?) than is shown in your tutorial (<www.zoho.com/mail/help/apple-mac-imap.html>). After plugging

    • Assistance Required for Migrating Data from Odoo Inventory to Zoho Inventory

      Hi Team, I previously used Odoo Inventory to manage my stock and transactions, and I’ve now moved to Zoho Inventory. I’d like to migrate my data from Odoo—including product details, stock, purchase, and vendor information- into Zoho Inventory for continuity

    • I need my entire Zoho Account (mail/organization) deleted!

      Hey! I used zoho for my email aaron@aaronglass.me with domain forwarding/mx all that. I got rid of the mx info on my godaddy account and still Google won't let me sign up with my aaron@aaronglass.me email. (I'm moving to Google for business) SO! I was

    • Error: "Invalid Element warehouse_id" when sending order to Zoho

      i'm getting the error "Invalid Element warehouse_id" when trying to send an order to Zoho via API. Has anyone faced this issue before? How can I fix it?

    • No way to sell individual and case units smoothly in Zoho

      Currently, Zoho Inventory handles inventory primarily at the case level, which can be challenging for businesses that frequently need to break down cases into individual units for retail sales or smaller shipments. Although Zoho Inventory currently supports

    • How to handle multiple languages (Resume parser, Job opening, job board, career site) ?

      We are looking to bring Zoho Recruit to a market that needs to support 2 languages. The first thing we need to make sure is that the Candidate be flag with the language they speak. This is easy enough make a custom field that as the desire languages.

    • Multi-Card Selection and Cross-Zobot Copy-Paste Functionality

      Dear Zoho SalesIQ Team, We’d like to suggest a productivity-enhancing feature for the Zobot builder in Zoho SalesIQ: the ability to select multiple cards (modules) at once using a selection area, and then copy-paste them either within the same canvas

    • Shipping Labels

      Hi, Can we generate Packing Labels for manual shipping same as the format as Airway Bill in zoho books or inventory?

    • Next Page